@database text.guide
@$VER: text.guide 1.2 (28.11.97)

@node MAIN "text_plugin: Introduction"


    @{b}text_plugin@{ub}

        by @{b}Ali Graham@{ub} <agraham@hal9000.net.au>



    @{b}text_plugin@{ub} is a simple equivalent to the
    TEXT gadget in EasyGUI, that can also use a different
    font than the window is using. It also features the
    justification of the text within the gadget to the
    left, right or middle.

    ------------------------------------------------------------

    @{"  " link TEXT_CONSTRUCTOR}  Constructor

    @{"  " link TEXT_METHODS}  Methods

    @{"  " link TEXT_TAGS}  Tags

    @{"  " link TEXT_EXCEPTIONS}  Exceptions

    @{"  " link TEXT_HISTORY}  History
    
@endnode

@node TEXT_CONSTRUCTOR "text_plugin: Constructors / Destructor"

   @{BG shine}Constructor@{BG back}

      @{b}text(@{"tags" link TEXT_TAGS}:PTR TO tagitem)@{ub}

      For creating a new plugin object use for example:
      @{FG fill}
      DEF text:PTR TO text_plugin
      NEW text.text([..., TAG_DONE])
      @{FG text}

@endnode

@node TEXT_METHODS "text_plugin: New Methods"

   @{b}set(@{"tag" link TEXT_TAGS}, value)@{ub}

      By calling this method it's possible to change attributes
      at runtime. You can use all tags with the S flag set.
      This method can also be used before the GUI is created and when
      the window is closed.
      Value is a LONG and contains the argument for the used tag.
      @{FG fill}
      Example:
      DEF text:PTR TO text_plugin
      ...
      NEW text.text([..., TAG_DONE])
      ...
      text.set(PLA_Text_Disabled, TRUE)
      ...
      @{FG text}

   @{b}value,check:=get(@{"tag" link TEXT_TAGS})@{ub}

      This method is the counterpart to set. All tags with G flag
      can be used. Argument is the tag you want to get. Return values
      are the requested value and as second a boolean value. So if
      check is FALSE the used tag can't be get.

      @{FG fill}...
      value,check:=text.get(PLA_Text_Disabled)
      ...@{FG text}

      After this:
       value=TRUE
       check=TRUE

      But if you try:

      @{FG fill}...
      value,check:=text.get(PLA_Text_Font)
      ...@{FG text}

      Then you get this:
       value:=-1
       check:=FALSE


   @{b}draw()@{ub}              @{FG shine}@{i}/* Private */@{ui}@{FG text}


@endnode

@node TEXT_TAGS "text_plugin: Tags"
 The letters [ISG] show you when the tags can be used.
 I = @{"Initalisation" link TEXT_CONSTRUCTOR}
 S = @{"Set Method" link TEXT_METHODS}
 G = @{"Get Method" link TEXT_METHODS 18}


    @{FG shine}PLA_Text_Text@{FG text}           [I.G]

        The contents of the text field.


    @{FG shine}PLA_Text_Highlight@{FG text}      [ISG]

        Boolean; whether or not the text should
        be rendered highlighted (in white) instead
        of normally (in black).


    @{FG shine}PLA_Text_ThreeD@{FG text}         [ISG]

        Boolean; whether or not the text should
        be rendered with a 3D look. Defaults to
        FALSE (and, when TRUE, will look different
        depending on whether or not @{FG shine}PLA_Text_Highlight@{FG text}
        is set).

    @{FG shine}PLA_Text_DrawBar@{FG text}        [ISG]

        Boolean; whether or not to draw a bar to the
        left and right of the text, to achieve a look
        similar to the old @{b}title_plugin@{ub}.
        Defaults to FALSE.


    @{FG shine}PLA_Text_Font@{FG text}           [I.G]

        The font that the text field should use. This
        is a pointer to a @{b}textattr@{ub} structure which
        represents an available font. Default is NIL;
        this means that the PLUGIN will use the
        window's font.


    @{FG shine}PLA_Text_Justification@{FG text}  [ISG]

        Set the justification of the text within the
        available space.

        Can be set to one of three values:

            PLV_Text_JustifyCenter
            PLV_Text_JustifyLeft
            PLV_Text_JustifyRight


    @{FG shine}PLA_Text_Disabled@{FG text}       [ISG]

        Disable or enable a gadget. Setting this tag causes the
        gadget to become disabled; it gets a ghost pattern.

@endnode

@node TEXT_EXCEPTIONS "text_plugin: Exceptions"

   @{BG shine}Constructor@{BG back}

      "util" will be raised if the utility.library has not
      been opened.


@endnode

@node TEXT_HISTORY "text_plugin: History"


    @{b}v1.0@{ub}                                   (2.10.97)

    o   Initial release.


    @{b}v1.1@{ub}                                   (28.10.97)

    o   Added text justification (left, right & center).

    o   Some sources using this module may need to be changed;
        the calling parameters of the initial method have been
        modified.

    o   Removed some unnecessary code from the render() method.


    @{b}v1.2@{ub}                                   (28.11.97)

    o   Rewritten to follow Ralph Wermke's PLUGIN Style Guide.

    o   Added the ability to disable the text field.

    o   Changed 3D mode, and added ability to draw bars (duplicates
        the functionality of the now defunct @{b}title_plugin@{ub}).

@endnode