?? pimitem.html
字號:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN""http://www.w3.org/TR/REC-html40/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<TITLE>PIMItem (PIM Optional Package 1.0 Spec, Final Release) </TITLE>
<!-- Generated by javadoc on Wed Oct 29 13:13:41 PST 2003 -->
<META NAME="keywords" CONTENT="javax.microedition.pim.PIMItem,PIMItem interface">
<LINK REL="stylesheet" TYPE="text/css" HREF="../../../stylesheet.css" TITLE="Style">
<SCRIPT>
function asd()
{
parent.document.title="PIMItem (PIM Optional Package 1.0 Spec, Final Release)";
}
</SCRIPT>
</HEAD>
<BODY BGCOLOR="white" onload="asd();">
<!-- ========== START OF NAVBAR ========== -->
<A NAME="navbar_top"><!-- --></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
<TR>
<TD COLSPAN="3" BGCOLOR="#eeeeff" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#eeeeff" CLASS="NavBarCell1">
<A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
<TD BGCOLOR="#eeeeff" CLASS="NavBarCell1">
<A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD>
<TD BGCOLOR="#ffffff" CLASS="NavBarCell1Rev">
<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD>
<TD BGCOLOR="#eeeeff" CLASS="NavBarCell1">
<A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
<TD BGCOLOR="#eeeeff" CLASS="NavBarCell1">
<A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
<TD BGCOLOR="#eeeeff" CLASS="NavBarCell1">
<A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
<TD BGCOLOR="#eeeeff" CLASS="NavBarCell1">
<A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN="3"><EM> PIM Optional Package 1.0<br>
Final Release</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> <A HREF="../../../javax/microedition/pim/EventList.html"><B>PREV
CLASS</B></A> <A HREF="../../../javax/microedition/pim/PIMList.html"><B>NEXT
CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2"> <A HREF="../../../index.html" TARGET="_top">
<B>FRAMES</B></A> <A HREF="PIMItem.html" TARGET="_top"><B>NO FRAMES</B></A>
<SCRIPT> <!-- if(window==top) { document.writeln('<A HREF="../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>'); } //--></SCRIPT>
<NOSCRIPT>
<A HREF="../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>
</NOSCRIPT>
</FONT>
</TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> SUMMARY: NESTED | <A HREF="#field_summary">FIELD</A> | CONSTR | <A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2"> DETAIL: <A HREF="#field_detail">FIELD</A> | CONSTR | <A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<!-- =========== END OF NAVBAR =========== -->
<HR>
<!-- ======== START OF CLASS DATA ======== -->
<H2>
<FONT SIZE="-1">javax.microedition.pim</FONT>
<BR>
Interface PIMItem</H2>
<DL>
<DT><B>All Known Subinterfaces:</B>
<DD>
<A HREF="../../../javax/microedition/pim/Contact.html">Contact</A>, <A HREF="../../../javax/microedition/pim/Event.html">
Event</A>, <A HREF="../../../javax/microedition/pim/ToDo.html">ToDo</A></DD>
</DL>
<HR>
<DL>
<DT>public interface <B>PIMItem</B></DT></DL>
<P>
Represents the common interfaces of an item for a PIM list. A PIM item
represents a collection of data for a single PIM entry. A PIM item is created
from a particular PIM list and is associated with that list for the life of the
item. PIM items can have its data imported and exported using standard byte
based formats. Each implementing class defines what formats can be imported and
exported for that item.
</P>
<H3>Fields</H3>
<P>PIMItems reference its data through <i>fields</i>. A field is a grouping of data
values that all have similar characteristics. An example of a field is TEL,
which indicates data values for that particular field are telephone numbers.
Classes implementing the PIMItem interface defines the possible fields that for
that specific class (e.g TEL is defined in the <code>Contact</code> interface
as a field that a contact may support).
</P>
<P>
PIM implementations are not required to support all of the possible fields
defined in the classes implementing the PIMItem interface. This is because no
native PIM databases contain all of the fields defined in this API. The PIMList
that a PIMItem belongs to determines what fields a PIMItem can support and
store (all PIMItems in a particular PIMList support the same set of fields).
The <A HREF="../../../javax/microedition/pim/PIMList.html#getSupportedFields()"><CODE>PIMList.getSupportedFields()</CODE></A>
method from a particular PIMItem's PIMList is used to find out what fields are
supported within this item. Since not all possible fields are actually
supported in a particular PIMItem, <B>all fields should be checked for support in
the item's PIMList using <A HREF="../../../javax/microedition/pim/PIMList.html#isSupportedField(int)">
<CODE>PIMList.isSupportedField(int)</CODE></A> prior to being used in any
retrieval or storage method.</B>
</P>
<p>
Each field has the following pieces of information available for it:
<UL>
<LI>
Zero or more <i>data values</i>
associated with the Field
<LI>
<i>Attributes</i>
for data values for the Field
<LI>
Descriptive <i>label</i>
for the Field
<LI>
<I>Data Type</I> of the data associated with the Field</LI>
</UL>
<h5>Data Values in a Field</h5>
<p>A single field can have zero or more data values associated with it at any
instance. All values within a field have the same data type as dictated by the
field (for example, all Contact.TEL field data values must be of STRING type).
The data type of a field determines the add/get/set methods to use for
accessing the data values (for example, if a field requires STRING data types,
then addString, getString, and setString methods are used to access the data).
</p>
<P>
Data values within a field are treated as a variable-length array of values,
very similar to the behavior of a <code>Vector</code>. As such, the following
rules apply for accessing data values for fields:<br>
<ul>
<li>
Values are added using the appropriate addXXX() method. The value is appended
as the last data value in the field's array, similar to <code>Vector.addElement</code>.
<li>
Values are retrieved one at a time using the appropriate getXXX() method with
an index. The index is an array index into the field's array of data values.
Values are assigned a sequential index beginning from 0 for the first value in
a field up to n-1, where n is the total number of values currently assigned to
the field. This behavior is similar to the method <code>Vector.elementAt()</code>.
<li>
Values are removed from a field by using the method <A HREF="../../../javax/microedition/pim/PIMItem.html#removeValue(int, int)">
<CODE>removeValue(int, int)</CODE></A>. All indexes in the field's array
are guaranteed by the implementation to contain an assigned value. Therefore,
removing fields from the middle of a field's array causes compacting of the
array and reindexing of the data values. This is similar behavior to the method <code>
Vector.removeElement(Object)</code>.</li>
</ul>
<h5>Field Labels</h5>
<p>Each field has a human readable <i>label</i>, usually used for display purposes.
The label can be retrieved through <A HREF="../../../javax/microedition/pim/PIMList.html#getFieldLabel(int)">
<CODE>PIMList.getFieldLabel(int)</CODE></A>.
</p>
<h5>Field Data Types</h5>
<p>The data values for a field has a <i>data type</i>, such as <A HREF="../../../javax/microedition/pim/PIMItem.html#INT">
<CODE>INT</CODE></A>, <A HREF="../../../javax/microedition/pim/PIMItem.html#BINARY">
<CODE>BINARY</CODE></A>, <A HREF="../../../javax/microedition/pim/PIMItem.html#BOOLEAN">
<CODE>BOOLEAN</CODE></A>, <A HREF="../../../javax/microedition/pim/PIMItem.html#DATE">
<CODE>DATE</CODE></A>, <A HREF="../../../javax/microedition/pim/PIMItem.html#STRING_ARRAY">
<CODE>STRING_ARRAY</CODE></A> or <A HREF="../../../javax/microedition/pim/PIMItem.html#STRING">
<CODE>STRING</CODE></A>. The data type of the field's data can be retrieved
through <A HREF="../../../javax/microedition/pim/PIMList.html#getFieldDataType(int)">
<CODE>PIMList.getFieldDataType(int)</CODE></A>. All data values for a
particular field have the same data type.
</p>
<h4>Standard and Extended Fields</h4>
<p>Fields can be classified into two logical divisions: standard fields and
extended fields. This division of fields generally determines the portability
of the fields across implementations. Standard fields are specifically defined
within the javax.microedition.pim package and may be available on almost all
PIM implementations. Extended fields are platform specific fields defined by an
individual implementation and are therefore generally not portable across
different devices. Extended fields are generally defined in vendor specific
classes derived from this class.
</p>
<h5>Standard Fields</h5>
<P>Standard fields are fields that have IDs explicitly defined as part of the PIM
APIs in the javax.microedition.pim package. These fields are the common fields
among PIM lists and are more likely to be portable across PIM implementations
(but not guaranteed since not all platforms support the same fields in a
PIMItem).
</P>
<h5>Extended Fields</h5>
<p>Extended fields are fields that do not have a specific field explicitly defined
in the javax.microedition.pim package, but are defined in vendor-specific
classes in a separate vendor package. These fields may or may not be exposed
publicly in vendor specific classes. Vendors are allowed to extend the field
set for any of the PIM items in this manner to address any platform specific
fields they wish to support. Users can find out if a field is an extended field
by comparing its value against <A HREF="../../../javax/microedition/pim/PIMItem.html#EXTENDED_FIELD_MIN_VALUE">
<CODE>EXTENDED_FIELD_MIN_VALUE</CODE></A>, find out the field's allowed
data type through the method <A HREF="../../../javax/microedition/pim/PIMList.html#getFieldDataType(int)">
<CODE>PIMList.getFieldDataType(int)</CODE></A>, and find out the field's
label through the method<A HREF="../../../javax/microedition/pim/PIMList.html#getFieldLabel(int)"><CODE>PIMList.getFieldLabel(int)</CODE></A>.
</p>
<h4>Attributes</h4>
<p>Optional attributes can be provided to further describe individual data values
for a field. Attributes are specified when adding data values to a field. These
attributes are hints to the underlying implementation providing more
information about the data value than just a field can provide. Since they are
hints, they may or may not be ignored by the implementation when adding the
data values. The actual attributes used and associated with the data values
after adding can be retrieved by the method <A HREF="../../../javax/microedition/pim/PIMItem.html#getAttributes(int, int)">
<CODE>getAttributes(int, int)</CODE></A>. Attributes can also have human
readable labels associated with them, retrieved by the method <A HREF="../../../javax/microedition/pim/PIMList.html#getAttributeLabel(int)">
<CODE>PIMList.getAttributeLabel(int)</CODE></A>. If no attributes are to be
associated with a data value, then <A HREF="../../../javax/microedition/pim/PIMItem.html#ATTR_NONE">
<CODE>ATTR_NONE</CODE></A> must be used.
</p>
<p>
Attributes are handled in the API using a single bit to indicate a specific
attribute and using int values as bit arrays to indicate a set of attributes.
int values can be checked to see if they contain a specific attribute by using
bitwise AND (&) with the attribute and the int value. <A HREF="../../../javax/microedition/pim/PIMItem.html#ATTR_NONE">
<CODE>ATTR_NONE</CODE></A> is a special attribute that indicates no
attributes are set and has a value of 0 that erases all other attributes
previously set.
</p>
<h5>Extended Attributes</h5>
<p>Optional attributes may also be extended by vendors and their PIM API
implementations. These extended attributes also may or may not be exposed
publicly in vendor specific classes. The label for these attributes can be
retrieved through <A HREF="../../../javax/microedition/pim/PIMList.html#getAttributeLabel(int)">
<CODE>PIMList.getAttributeLabel(int)</CODE></A>.
?? 快捷鍵說明
復制代碼
Ctrl + C
搜索代碼
Ctrl + F
全屏模式
F11
切換主題
Ctrl + Shift + D
顯示快捷鍵
?
增大字號
Ctrl + =
減小字號
Ctrl + -