PtText

Gamma/Photon: Using Gamma™ with the Photon microGUIŽ, Version 4.0
Prev |  | Next

# `PtText`

`PtText` -- A single-line or multi-line text entry/display field.

## Synopsis

    class PtText PtLabel
    {
        columns;            // short  (Pt_ARG_COLUMNS)
        cursor_position;    // short  (Pt_ARG_CURSOR_POSITION)
        edit_mask;          // string  (Pt_ARG_EDIT_MASK)
        max_length;         // short  (Pt_ARG_MAX_LENGTH)
        text_flags;         // flag  (Pt_ARG_TEXT_FLAGS)
    }

## Base Classes

`PtWidget` <-- `PtBasic` <-- `PtLabel` <-- `PtText`

## Description

This widget is a box that accepts text entry and displays text strings. Its cursor toggles between insert and replace modes, and can be used to select ranges of text. Possible callbacks include text changes, cursor movements, and pressing the Enter key.

| For detailed information, please refer to PtText in the Photon documentation.

## Instance Variables

columns

  An integer specifying the width of the widget in columns, where each column is the width of the character 'M'. This variable will take effect only if the `dim` variable for the widget is set to nil.

cursor_position

  An integer specifying the number of characters to the left of the cursor. Default is `-1`.

edit_mask

  This variable is not currently implemented.

max_length

  An integer specifying the maximum number of characters the widget will accept.

text_flags

  This instance variable controls certain characteristics of the widget, and may be a combination of zero or more of the following flags:

  Constant | Description
  --- | ---
  `Pt_CURSOR_VISIBLE` | Makes the cursor as visible. Default is ON.
  `Pt_EDITABLE` | Makes the text editable. Default is ON.
  `Pt_INSERT_MODE` | Toggles between insert and replace modes. Default is insert.
  `Pt_TEXT_AUTO_HIGHLIGHT` | Highlights text when widget has focus. Default is OFF.
  `Pt_CHANGE_ACTIVATE` | Internal informational bit.
  `Pt_EDIT_ACTIVATE` | Internal informational bit.
  `Pt_TEXT_FULL` | Internal informational bit.
  `Pt_NO_RANGE_SELECTION` | Internal informational bit.
  `Pt_RESIZE_WIDTH` | Internal informational bit.
  `Pt_TEXT_RANGE_ACTIVE` | Internal informational bit.
  `Pt_TEXT_CHANGED` | Internal informational bit.

## Callbacks

The following callbacks are associated with this widget:

Callback | Description
--- | ---
`Pt_CB_MODIFY_VERIFY` | This callback is generated when a text string is going to be changed.
`Pt_CB_TEXT_CHANGED` | This callback is generated when the text string value changes (same as modify_notify.
`Pt_CB_MODIFY_NOTIFY` | This callback is generated when the text string value changes (same as text_changed.
`Pt_CB_MOTION_VERIFY` | This callback is generated when the cursor position is going to be changed.
`Pt_CB_MOTION_NOTIFY` | This callback is generated when the cursor position has changed.

## Associated Classes

`PtComboBox`, `PtCallbackInfo`, `PtTextCallback`

## Convenience Functions

### Arguments

`widget` | `A PtText widget.`
`start` | The start of the selected text.
`end` | The end of the selected text.

### Functions

These functions are extensions of QNX Photon functions. You can refer to the PtText function documentation in QNX Helpviewer for more information about them.

`numchars = PtTextGetSelection` `(widget)` -- gets a range of text previously selected with `PtTextSetSelection`.

Returns the number of characters selected, or -1 to indicate that the `widget` is not a `PtText` widget.

`numchars = PtTextSetSelection` `(widget, start, end)` -- Selects text specified by `start` and `end`. If `start` and `end` are equal to each other, or if they are both greater than the number of characters in the `widget`, this function may return 0.

Returns the number of characters selected, or -1 to indicate that the `widget` is not a `PtText` widget.

## Example

This example, `ex_PtText.g`, is included in the `gamma_ph_`#`_examples_1_QNX4.tgz` file available on the Cogent Web Site.

    #!/usr/cogent/bin/phgamma

    /*
     * This example puts 3 PtText widgets into a window.
     * The first is a text_entry box, whose width is specified at 12
     * columns (M_width), and whose maximum length is 15 characters.
     * The second displays the cursor position in the entry box.
     * The third displays the text entered when the Enter key is pressed.
     */
    require_lisp("PhotonWidgets.lsp");
    require_lisp("PhabTemplate.lsp");
    PtInit(nil);

    wfile = PhabReadWidgetFile ("WidgetFiles/wgt/text.wgtw");
    window = PhabCreateWidgets(wfile, nil, nil);

    win = PhabLookupWidget(window,#text,nil);
    tx1 = PhabLookupWidget(window,#PtText1,nil);
    tx2 = PhabLookupWidget(window,#PtText2,nil);
    tx3 = PhabLookupWidget(window,#PtText3,nil);
    prg = PhabLookupWidget(window,#RtProgress,nil);

    /*
     * Specify the characteristics of the PtText widgets.
     */
    tx1.dim = nil;
    tx1.columns = 12;
    tx1.max_length = 15;
    tx3.max_length = 10;
    tx2.text_flags = cons(Pt_EDITABLE, nil);
    tx3.text_flags = cons(Pt_EDITABLE, nil);

    /*
     * Attach callbacks for text changes, cursor motion, and pressing
     * the Enter key.
     */
    PtAttachCallback(tx1, Pt_CB_TEXT_CHANGED,
                     #entry = tx1.text_string);

    PtAttachCallback(tx1, Pt_CB_MOTION_NOTIFY,
                     #tx2.text_string = string(tx1.cursor_position));

    PtAttachCallback(tx1, Pt_CB_ACTIVATE, #tx1.text_string = "");
    PtAttachCallback(tx1, Pt_CB_ACTIVATE, #tx2.text_string = "");
    PtAttachCallback(tx1, Pt_CB_ACTIVATE, #tx3.text_string = entry);

    PtRealizeWidget(win);
    PtMainLoop();

Prev | Home | Next
`PtTerminal` | Up | `PtToggleButton`

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.