docs/LabelTextIClass.doc

   1 TABLE OF CONTENTS
   2
   3 labeltext.image/labeltext.image
   4 \flabeltext.image/labeltext.image           labeltext.image/labeltext.image
   5
   6     NAME
   7         labeltext.image -- label BBOPSI image (V1)
   8
   9     FUNCTION
  10         The labeltext class is a little BOOPSI class that provides a complete
  11         label handling. A label can be placed inside or outside a gadget
  12         (above, below, left, right or inside) with different alignments
  13         (centered, left aligned, right aligned, etc.) with a couple of
  14         different rendering methods (normal, hilighted, 3d). It is able to
  15         use the standard DrawInfo pens when no custom pens are supplied and
  16         the system default font when no custom font is supplied.
  17         It supports various image states (i.e. normal, selected, disabled,
  18         etc.) This class has also a nice API for easy layer clipping when it
  19         is necessary.
  20
  21     METHODS
  22         IM_DRAW -- Tell the class to render itself. Before calling this
  23             method for the first time you should first invoke the IM_FRAMEBOX
  24             method and then the IM_DRAW one using the FrameBox Left and Top
  25             field or the Image LeftEdge and TopEdge fields. Note that these
  26             coordinates are NOT exactly the ones the label will use, i.e.
  27             if you do a Text() call using that coordinates you'll get a text
  28             slightly shifted. In other words if you calculate yourself the
  29             coordinates of the label you won't be able to draw it in the right
  30             place. This is required for an easy layer clipping support.
  31             NB: You must alway supply the imp_Offset coordinates, even if the
  32             Image->LeftEdge and Image->TopEdge field already contain the right
  33             values.
  34
  35         IM_FRAMEBOX -- This method tell the class to calculate its position
  36             relative to the ContentsBox coordinates and according to its
  37             alignment attributes. For this reason the ContenstBox is usually
  38             filled with the gadgets coordinates. Moreover the FrameBox structure
  39             is filled with the coordinates of the rectangle required by the
  40             label to draw itself. In this way the gadget can easily perform
  41             the correct layer clipping if necessary. Example:
  42
  43
  44             struct IBox cbox, fbox;
  45             struct Rectangle rect;
  46
  47             DoMethod((Object *)gad->GadgetText, IM_FRAMEBOX, (ULONG)&(cbox), (ULONG)&fbox, NULL);
  48
  49             rect.MinX = MAX(msg->gpr_GInfo->gi_Window->BorderLeft, fbox.Left);
  50             rect.MinY = MAX(msg->gpr_GInfo->gi_Window->BorderTop, fbox.Top);
  51             rect.MaxX = MIN(msg->gpr_GInfo->gi_Window->Width - msg->gpr_GInfo->gi_Window->BorderRight,
  52                             fbox.Left + fbox.Width - 1);
  53             rect.MaxY = MIN(msg->gpr_GInfo->gi_Window->Height - msg->gpr_GInfo->gi_Window->BorderBottom,
  54                             fbox.Top + fbox.Height - 1);
  55
  56             OrRectRegion(new_region, &rect);
  57             old_region = InstallClipRegion(msg->gpr_GInfo->gi_Layer, new_region);
  58
  59
  60             The same rectangle is then usually used to tell the label to draw
  61             or erase itself (using the Left and Top field) but it is not
  62             required, since the class modifies its coordinates with the values
  63             it calculated the last time IM_FRAMEBOX was invoked (i.e. you may
  64             alternatively supply the img->LeftEdge and img->TopEdge values).
  65
  66             If you specify the FRAMEF_SPECIFY flag the label will check if it
  67             fit in the ContentsBox rectangle. If not the FrameBox Left and
  68             Top fields will be set to -1. You can blindly pass this values
  69             to the IM_DRAW or IM_ERASE method, since the class knows that it
  70             has not to render itself. The FrameBox Width and Height fields
  71             are set to an arbitrary value to avoid problems if the gadget do
  72             layer clipping without checking the result of the IM_FRAMEBOX
  73             method.
  74
  75             NOTE: If you change some attributes (e.g. the font) you should call
  76             the IM_FRAMEBOX method again, so that the label can recalculate
  77             its position and size.
  78
  79     TAGS
  80
  81         ELA_Label -- Pointer to the string the class will print. You MUST
  82             supply this tag when you create an object. The label will not
  83             deallocate the string when disposed.
  84
  85             Applicability is (ISG)
  86
  87         ELA_LabelType -- Specify the way the label should render itself. See
  88             the include file for the currently supported values.
  89
  90             Applicability is (ISG)
  91
  92         ELA_Distance -- The distance from the gadget borders. Note that the
  93             label does not know about frame thickness. e.g. if you draw a
  94             label inside a gadget, left aligned with a distance of 0 pixel,
  95             the label will likely draw itself over the left border of the
  96             frame. If you want to avoid this you must set this attribute to
  97             a value at least equal to the frame thickness.
  98
  99             Applicability is (ISG)
 100
 101         ELA_Position -- Tell the label where it should draw itself, i.e.
 102             above the gadget, below, to the left, etc. Note that 'gadget'
 103             is somewhat misleading, since the label calculates its position
 104             relative to any rectangle. i.e. when you call the IM_FRAMEBOX
 105             method, you usually pass as the ContentsBox the gadget
 106             coordinates, but if you want you could, e.g. tell the label
 107             to center itself in the window titlebar.
 108             See the include file for the values of this tag.
 109
 110             Applicability is (ISG)
 111
 112         ELA_Align -- Set the alignment of the label. If the label is placed
 113             above or below the gadget the label can be centered, left aligned
 114             or right aligned. If placed to the side of the gadget it can be
 115             vertically centered or aligned to the top or to the bottom of the
 116             gadget. If it is placed inside it can be centered, aligned to the
 117             top or bottom (always horizontally centered) or aligned to the
 118             left or right (vertically centered).
 119
 120             Applicability is (ISG)
 121
 122         ELA_Font -- Specify the font the label will use to draw itself.
 123             It must be a TextFont pointer, i.e. the one you'll get with
 124             the OpenFont() function. The label will not close the font
 125             when disposed.
 126
 127             Applicability is (ISG)
 128
 129         ELA_PenBackgound -- Specify the pen number used for the background
 130             pen. If it is not specified or set to -1 the standard DrawInfo
 131             BACKGROUNDPEN will be used. Currently it is used only to erase
 132             the label.
 133
 134             Applicability is (ISG)
 135
 136         ELA_PenShine -- Specify the pen number used for the shine pen.
 137             If it is not specified or set to -1 the standard SHINEPEN will
 138             be used. Currently this is used for the 'hilight' and '3d' labels.
 139
 140             Applicability is (ISG)
 141
 142         ELA_PenShadow -- Specify the pen number used for the shadow pen.
 143              If it is not specified or set to -1 the standard SHADOWPEN will
 144              be used. This is the pen used for 'normal' and '3d' labels.
 145
 146             Applicability is (ISG)
 147
 148         ELA_PenHalfShine -- Specify the halfshine pen. If it is not specified
 149             or set to -1 the standard SHINEPEN will be used. It's usually a
 150             bit darker than the shine pen and is currently used for the
 151             disabled state.
 152
 153             Applicability is (ISG)
 154
 155         ELA_PenHalfShadow -- Specify the halfshadow pen. If it is not
 156             specified or set to -1 the standard SHADOWPEN will be used.
 157             It'susually a bit brighter than the shadow pen and is currently
 158             used for the disabled state.
 159
 160             Applicability is (ISG)
 161
 162     NOTE
 163         Usually a single BOOPSI image (e.g. a frame) may be used by different
 164         gadgets at the same time. This is true even for the textlabel class,
 165         but there are a couple of little "problem" or side effects that may
 166         be encountered. First every time the IM_FRAMEBOX method is called the
 167         image LeftEdge and TopEdge fields are changed, so the gadgets should
 168         take care of storing the result of this method by their own (i.e. they
 169         should save the FrameBox Left and top fields somewhere), since if they
 170         call the IM_DRAW method using the image coordinates they may use the
 171         result of another gadget's IM_FRAMEBOX call. Second the text to be
 172         printed (and maybe even the font) should be set every time before a
 173         IM_DRAW method since it's very unlikely that different gadgets need to
 174         display the same string.
 175         Currently I don't know if there's some nice and elegant way to solve
 176         this, so you should create a different instance of this class for every
 177         gadget that will use a lebeltext object.
 178
 179     SEE ALSO
 180         The "Image Subclasses" chapter of the Intuition Reference Manual.
 181