PField


This is class represents a text field. This class is a little bit problematic, because of PalmOS's intrinsic memory handling. PalmOS seems to allow a field to grow, shrink and delete the block of memory it has assigned. So read the descriptions of PField(...), text(PString&) and handle(Handle) carefully.

Synopsis

#include <PLField.h>

Derivation

  • PControl
  • PField
  • Constructors

        PField(PForm* parent, Word id,
               Word scrollbarId,
               PString& initialText = 0, Boolean keepText = false);
    
    Contructs a field from the resource id and adds it to parent as a child. Specifying initialText and keep does the same thing as calling text(initialText, keepText) . Please read this and the notes to handle(Handle)carefully.

        PField(PForm* parent, Word id,
               Word scrollbarId,
               PString& initialText = 0, Boolean keepText = false);
    
    Attaches a scrollbar from a resource id to the field. The class runtime does the adjustment and the handling of the scrollbar. There is no overlap when scrolling. I will allow this in the future. Again, please read text(initialText, keepText) and handle(Handle).


        PField(PForm* parent, FieldPtr fieldPtr);
    
    Creates a Field from a FieldPtr returned by the system. This is intended for internal use by tables only (BTW, keep is set to true).

    Public functions

        PString text();
    
    Returns the field's contents as a PString


        PField& text(const PString& text, Boolean keepText = false);
    
    A new memory handle will be created, the text will be copied to it and the field's text handle will be set. When the object is destroyed, the field's handle will be set to 0 and the allocated memory will be freed, unless keepText is set to true. In this case, the handle will be left to the field and will be freed when the form is closed. Leaving keepText false will result in an empty field when the object is destroyed.
    The allocated handle cannot be retrieved with handle() if keepText is false and will be freed when the form is closed or the application sets it explicitely with handle(Handle h).


        Handle handle();
    
    Returns the handle of the field's allocated text memory, if available to the application, 0 otherwise. It's length can be retrieved with allocated().


        PField& handle(Handle h, Boolean keepHandle = true);
    
    Sets the field's memory handle. The meaning of keepHandle differs from the one of text(PString&). If it is true (default) the memory will be left to the application. That is, if a form is closed or another call to handle(Handle) is made, the field's internal handle is reset to 0 respectively replaced. If it false, the field takes over the management of the handle. Closing a form or calling handle(Handle) again will release and invalidate the memory. Be very carefull with this when passing handles to database records! You can explicetely avoid this by calling handle(0). In opposite to text(PString&) only non-kept handles can be retrieved by handle() and allocated().


        PField& attachScrollbar(Word id);
    
    Associates a scrollbar with a field. See
    constructors for details.


        PField& scroll(enum directions dir, short lines = 0)
    
    Scrolls the field. dir can be either up or down. If lines is omitted, the field scrolls the number of visible lines.


        FieldPtr fieldPtr();
    
    Returns the FieldPtr if the parent form is already shown, otherwise it returns 0. This can be used to access PalmOS APIs that are not implemented yet.
    For the reasons mentioned above, be carefull when using memory related APIs.


        PField& underline(Boolean underlined = true);
        Boolean underlined();
    
    Set and query the underlined attribute of a field.


        PField& grabFocus(Boolean focus = true);
        PField& relaseFocus();
    
    Grabs or releases the focus. These functions do not always work, don't ask me why.


    See PControl for inherited public functions.

    Protected functions

    See PControl for inherited protected functions.