src/bind/java/org/w3c/dom/views/Segment.java

   1 /*
   2  * Copyright (c) 2004 World Wide Web Consortium,
   3  *
   4  * (Massachusetts Institute of Technology, European Research Consortium for
   5  * Informatics and Mathematics, Keio University). All Rights Reserved. This
   6  * work is distributed under the W3C(r) Software License [1] in the hope that
   7  * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
   8  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   9  *
  10  * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
  11  */
  12
  13 package org.w3c.dom.views;
  14
  15 import org.w3c.dom.Node;
  16
  17 /**
  18  *  <code>Segment</code> is used to retrieve specific items from specific
  19  * segments. Segments may be nested as a match and may be repeatedly applied
  20  * for traversing multiple matching segments.
  21  * <p ><b>Note:</b>  Types and names of properties of segments of Visual media
  22  * types
  23  * <pre> Integer TopOffset Integer BottomOffset Integer LeftOffset Integer
  24  * RightOffset Integer Width Integer Height Boolean Visible Boolean Selected
  25  * Integer ForegroundColor Integer BackgroundColor String FontName String
  26  * FontHeight String FontBaseline String FontSpace Width String FontMaximum
  27  * Width </pre>
  28  *
  29  * <p ><b>Note:</b> Segment types
  30  * <pre> // Display info and root (the default
  31  * segment) Display // An area that objects or text lines flow in // or are
  32  * anchored to Frame // A single character Character //
  33  * Sequentially-appearing characters // with identical properties
  34  * CharacterRun FormField {Text | Label | Button | Menu ...} Embedded Object
  35  * Image </pre>
  36  *
  37  * <p ><b>Note:</b> Possible properties of specific types:
  38  * <pre> (Image) String URL
  39  * (Image) Boolean isLoaded (Image) Integer ScalingFactor (Button) Boolean
  40  * isPressed (Frame) Boolean isScrollable </pre>
  41  *
  42  * <p>See also the <a href='http://www.w3.org/TR/2004/NOTE-DOM-Level-3-Views-20040226'>Document Object Model (DOM) Level 3 Views and Formatting
  43 Specification</a>.
  44  * @since DOM Level 3
  45  */
  46 public interface Segment extends Match {
  47     /**
  48      *  The <code>criteria</code> <code>Match</code> of a <code>Segment</code>
  49      * , specified during creation, controls which <code>Segment</code>s
  50      * will match.
  51      * <br>After setting this attribute, the results of any related call to
  52      * <code>getNext</code> are unpredictable until the segment has been
  53      * requested again by calling <code>matchFirstSegment</code>.
  54      */
  55     public Match getCriteria();
  56     /**
  57      *  The <code>criteria</code> <code>Match</code> of a <code>Segment</code>
  58      * , specified during creation, controls which <code>Segment</code>s
  59      * will match.
  60      * <br>After setting this attribute, the results of any related call to
  61      * <code>getNext</code> are unpredictable until the segment has been
  62      * requested again by calling <code>matchFirstSegment</code>.
  63      */
  64     public void setCriteria(Match criteria);
  65
  66     /**
  67      * The <code>order</code> string of a <code>Segment</code>, specified
  68      * during creation, controls the order in which matching segments will
  69      * be returned. If this attribute is not specified, the order defaults
  70      * to an implementation-specific order.
  71      * <br>After setting this attribute, the results of any related call to
  72      * <code>getNext</code> are unpredictable until the segment has been
  73      * requested again by calling <code>matchFirstSegment</code>.
  74      */
  75     public String getOrder();
  76     /**
  77      * The <code>order</code> string of a <code>Segment</code>, specified
  78      * during creation, controls the order in which matching segments will
  79      * be returned. If this attribute is not specified, the order defaults
  80      * to an implementation-specific order.
  81      * <br>After setting this attribute, the results of any related call to
  82      * <code>getNext</code> are unpredictable until the segment has been
  83      * requested again by calling <code>matchFirstSegment</code>.
  84      */
  85     public void setOrder(String order);
  86
  87     /**
  88      * Adds a specific <code>Item</code> to the <code>Segment</code>.
  89      * @param add The <code>Item</code> to be added.After adding a result,
  90      *   the results of any related call to <code>getNext</code> are
  91      *   unpredictable until the segment has been requested again by calling
  92      *   <code>matchFirstSegment</code>.
  93      */
  94     public void addItem(Item add);
  95
  96     /**
  97      * Creates a match for a string value, which can be used to specify a
  98      * criterium to find desired segments.
  99      * @param test The match test desired.
 100      * @param name The name of a string property to be compared against.
 101      * @param value The string value to be compared against.
 102      * @return The requested <code>MatchString</code>.
 103      */
 104     public MatchString createMatchString(short test,
 105                                          String name,
 106                                          String value);
 107
 108     /**
 109      * Creates a match for an integral value, which can be used to specify a
 110      * criterium to find desired segments.
 111      * @param test The match test desired.
 112      * @param name The name of an integer property to be compared against.
 113      * @param value The integer value to be compared against.
 114      * @return The requested <code>MatchInteger</code>.
 115      */
 116     public MatchInteger createMatchInteger(short test,
 117                                            String name,
 118                                            int value);
 119
 120     /**
 121      * Creates a match for a boolean value, which can be used to specify a
 122      * criterium to find desired segments.
 123      * @param test The match test desired.
 124      * @param name The name of a boolean property to be compared against.
 125      * @param value The boolean value to be compared against.
 126      * @return The requested <code>MatchBoolean</code>.
 127      */
 128     public MatchBoolean createMatchBoolean(short test,
 129                                            String name,
 130                                            boolean value);
 131
 132     /**
 133      * Creates a match for a content value, which can be used to specify a
 134      * criterium to find desired segments.
 135      * @param test The match test desired.
 136      * @param name The name of an integer property to be compared against.
 137      * @param offset The offset of the content value to be compared against.
 138      * @param nodeArg The Node of the content value to be compared against.
 139      * @return The requested <code>MatchContent</code>.
 140      */
 141     public MatchContent createMatchContent(short test,
 142                                            String name,
 143                                            int offset,
 144                                            Node nodeArg);
 145
 146     /**
 147      * Creates a match for an set of matches, which can be used to specify a
 148      * criterium to find desired segments.
 149      * @param test The match test desired.
 150      * @return The requested <code>MatchSet</code>.
 151      */
 152     public MatchSet createMatchSet(short test);
 153
 154     /**
 155      * Creates an item for a segment that can receive a string value.
 156      * @param name The name of a string property to be received.
 157      * @return The requested <code>StringItem</code>.
 158      */
 159     public StringItem createStringItem(String name);
 160
 161     /**
 162      * Creates an item for a segment that can receive an integral value.
 163      * @param name The name of an integral property to be received.
 164      * @return The requested <code>IntegerItem</code>.
 165      */
 166     public IntegerItem createIntegerItem(String name);
 167
 168     /**
 169      * Creates an item for a segment that can receive a boolean value.
 170      * @param name The name of a boolean property to be received.
 171      * @return The requested <code>BooleanItem</code>.
 172      */
 173     public BooleanItem createBooleanItem(String name);
 174
 175     /**
 176      * Creates an item for a segment that can receive a content value.
 177      * @param name The name of a content property to be received.
 178      * @return The requested <code>ContentItem</code>.
 179      */
 180     public ContentItem createContentItem(String name);
 181
 182     /**
 183      *  Returns a specific <code>Item</code>, of the list specified during the
 184      * creation of the <code>Segment</code>, which is to be fetched during
 185      * <code>Segment</code> execution, or returns null if the specified
 186      * index does not correspond to a <code>Item</code>.
 187      * @param index The index of the <code>Item</code> to be retrieved.
 188      */
 189     public void getItem(int index);
 190
 191     /**
 192      * Fetches the results of the next matching <code>Segment</code>, if any.
 193      * @return  <code>true</code> if another match, otherwise
 194      *   <code>false</code> (same value as <code>exists</code>).
 195      */
 196     public boolean getNext();
 197
 198 }