%C_CONTAINER

Perform composite window operations

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
value = %C_CONTAINER(subfunction, args)

or

xcall C_CONTAINER(subfunction, args)

Return value

value

A value specific to the subfunction.

Arguments

subfunction

One of the following: (n)

DC_ADD

Add a child window or list to a composite window.

DC_BTNFOCUS

Determine whether a button on a composite window has focus and return the tabbing index for the button and/or change focus to a specified button. (Windows only)

DC_CHILD

Determine whether a child exists for a given tabbing index and, if so, return the type and ID of the child.

DC_CHILDINDEX

Determine whether a window or list is a child and, if it is, return the tabbing index for the child.

DC_CONTAINER

Return the ID of the container window associated with a child or, if the window or list is not a child, indicate this by returning zero.

DC_CONTEXT

Use a tabbing index to change the active child for a composite window, and indicate which child is active by returning the tabbing index for that child.

DC_CREATE

Create a composite container window.

DC_CTRCONTEXT

Set the active child or button based on a code that indicates the reason the container received focus.

DC_ENABLE

Determine if a child window or list is enabled or disabled and/or enable or disable the child window or list.

DC_EVENT

Register an extension to the standard event methods for a child window or list.

DC_GETEVENT

Return the address for a currently registered extension for an event method for a child window or list.

DC_NUMCHILD

Return the number of children (windows and lists) associated with a composite container window.

DC_REMOVE

Remove a child window or list from a composite window.

args

One or more arguments, depending on subfunction.

Discussion

%C_CONTAINER enables you to create a composite container window, add child windows and lists, set options, and get information about options for the composite window (button focus, input context for a child input window, and so forth). See the individual subfunctions for details.

Examples

The following example creates and processes a composite window that includes a list and an input window to display and accept contact information. It also uses an ActiveX control to display an image and another for text editing. Note that the window script file and repository schema are included at the end of this example.

main composite
;
; Example of composite window usage
;
.include "WND:tools.def"
.align
stack record
    id_col    ,i4    ;ID of the general menu column
proc
    xcall u_start("composite", 1)
    xcall m_ldcol(id_col,, "c_general",,,, D_GLOBAL)
    xcall e_sect("Composite window example", D_HEADER)
    do
      xcall composite_example
    until (g_select)
    xcall u_finish
.end

subroutine composite_example
;
; Description: XCALLable example of composite window processing
;
; Arguments:   None
;
.include "DBLDIR:windows.def"
.include "WND:tools.def"
.align
stack record
    chan_contacts  ,i4  ;Channel for updating the contacts database
    chan_icontacts ,i4  ;Channel for loading the contacts
    id_container   ,i4  ;ID of the container
    id_listwnd     ,i4  ;ID of the list input window
    id_list        ,i4  ;ID of the list
    id_selcol      ,i4  ;ID of a selection column for non-windows
    id_contact     ,i4  ;ID of the contact input window
    id_inpcol      ,i4  ;ID of an input column for non-windows
    id_text        ,i4  ;ID of a text window
    id_editcol     ,i4  ;ID of an edit column for non-windows
    id_image       ,i4  ;ID of the ActiveX image window
    id_imgbtn      ,i4  ;ID of the "Image..." button window
    request        ,i4  ;List request
    read_one       ,i4  ;Did we read a record?
    err            ,i4  ;Error encountered
.include "contact" repository, record="list_contact"
.include "contact" repository, record="inp_contact"
.define D_KEYSIZ  ,(^size(list_contact.lastname) + ^size(list_contact.firstname))
proc
    xcall e_enter
    xcall e_state(D_RETURNBTN)
    xcall e_method(D_METH_ENTRST, "entrst")
    call do_setup
    do
      call do_process
    until (g_select)
    xcall e_exit
    xreturn

;
; do_setup - create and place windows
;
do_setup,
    ;Connect to the database.
    xcall u_open(chan_contacts, "U:I", "contacts",,, err)
    if (err)
      begin
        if (err == $ERR_FNF) then
          begin
            xcall isamc("contacts", ^size(list_contact), 1,
            &           "start=1,length="+%string(D_KEYSIZ))
            goto do_setup
          end
        else
          xcall u_abort("Unable to open Contacts database, 
          &             error = " + %string(err))
      end
    clear read_one    ;No file context yet
    ;Open again read-only for loading.
    xcall u_open(chan_icontacts, "I:I", "contacts",,, err)
    ;Create the container and add the desired buttons.
    id_container = %c_container(DC_CREATE, "", g_bdysiz,
    &                          %w_info(WIF_SCOLS))
    xcall b_button(id_container, DSB_ADD, "O_ADD", DSB_TEXT, "Add",,, "a")
    xcall b_button(id_container, DSB_ADD, "O_DEL", DSB_TEXT, "Delete"
    &              ,,, "d")
    xcall b_button(id_container, DSB_ADD, "O_EXIT", DSB_TEXT, "Exit"
    &              ,,, "x")
    ;Next, create the list and add it to the container.
    xcall i_ldinp(id_listwnd,, "il_contacts")
    xcall l_create(id_list, id_listwnd, list_contact, g_utlib,
    &              "l_contacts",,,,,1, %isinfo(chan_icontacts,"NUMRECS"))
    xcall l_sect(id_list, "Contacts", D_HEADER)
.ifdef D_GUI
    clear id_selcol, id_inpcol
.else
    xcall m_ldcol(id_selcol,, "c_listsel")
    xcall m_ldcol(id_inpcol,, "c_input")
.endc
    xcall c_container(DC_ADD, id_container, DC_LIST, id_list, 1, 1, 3
    &                ,,, id_selcol)

    ;Next, the input window
    xcall i_ldinp(id_contact,, "i_contact")
    xcall i_frames(id_contact)
    xcall c_container(DC_ADD, id_container, DC_WINDOW, id_contact, 8, 40,
    &                 4,,, id_inpcol)
    ;Next, a text window for editing notes
.ifdef D_GUI
    ;On Windows, we'll use a nice multi-line edit control
    id_text = %ax_tksingle("", 6, 40, "SYNNOTES.SynNotesCtrl.1",
    &                      "SynNotes.ocx",, "notes_")
    clear id_editcol
.else
    ;On non-Windows, we'll use a T_EDIT window
    xcall w_proc(WP_CREATE, id_text, "", 6, 40)
    xcall u_logwnd(id_text)
    xcall t_setup(id_text)
    xcall m_ldcol(id_editcol,, "c_edit")
.endc
    ;Regardless, C_PROCESS knows what method to use by default.
    xcall c_container(DC_ADD, id_container, DC_WINDOW, id_text, 13, 40,,,,
    &                 id_editcol)
.ifdef D_GUI
    ;Now an image control
    id_image = %ax_tksingle("", 6, 19, "SYNIMAGE.SynImageCtrl.1",
    &                       "SynImage.ocx")
    ;We have no need to put this into the tabbing order, so we use method 
    ; c_methnop.
    xcall c_container(DC_ADD, id_container, DC_WINDOW, id_image, 1, 40,,
    &                 "c_methnop")
    xcall i_ldinp(id_imgbtn,, "i_imagebtn")
    xcall c_container(DC_ADD, id_container, DC_WINDOW, id_imgbtn, 4, 
    &                 61, 4)
.endc
    ;Place the container and maximize it.
    xcall u_window(D_PLACE, id_container, 1, 1)
    xcall w_proc(WP_STATE, id_container, WPS_MAXIMIZED)
    return

;
; do_process - run the input loop
;
do_process,
    xcall c_process(id_container, chan_icontacts, chan_contacts,
    &               list_contact, inp_contact)
    if (g_select)
      begin
        using g_entnam select
("O_ADD   "),    call add
("O_DEL   "),    call delete
("O_SEL   "),    call select
("O_IMAGE "),    call image
("O_EXIT  "),    begin
                   call update
                   g_select = TRUE    ;Force exit from loop.
                 end
        endusing
      end
    return
;
; load_contact - load windows from inp_contact
;
load_contact,
    xcall i_display(id_contact,, inp_contact)
.ifdef D_GUI
    xcall ax_tkset(id_image, "ImagePath", %atrim(inp_contact.image))
    xcall ax_tkset(id_text, "Text", %atrim(inp_contact.notes))
.else
    xcall w_area(id_text, WA_COPY, WAC_WTOP)
    xcall w_info(WI_XFR, id_text, WIX_DPUT, inp_contact.notes)
.endc
    return
;
; add - add a new, empty contact
;
add,
    clear g_select
    xcall l_findspec(id_list, inp_contact,,,,,, D_LFND_CURR)
    call update
    clear inp_contact
    call load_contact
    xcall i_init(id_contact)
    xcall c_container(DC_CONTEXT, id_container, 2)   ;Focus input window.
    xcall l_selstyle(id_list, D_OFF)
    return
;
; delete - delete the current contact
;
delete,
    clear g_select
    if (read_one && (%u_msgbox("Really delete this contact?", D_MYESNO)
                    &          == D_MIDYES))
      begin
        delete(chan_contacts) [err=delerr]
        clear read_one, inp_contact
.ifdef D_GUI
        xcall ax_tkset(id_text, "Text", "")
.else
        xcall w_area(id_text, WA_COPY, WAC_WTOP, WA_FILL, ' ')
.endc
      end
    call add
    return
delerr,
    xcall u_msgbox("Could not delete, error = " + %string(%ernum))
    clear read_one
    return
;
; select - select the contact in the list
;
select,
    clear g_select
    xcall l_findspec(id_list, list_contact,,,,,, D_LFND_CURR)
    call update
    read(chan_contacts, inp_contact, list_contact(1:D_KEYSIZ))
    read_one = TRUE
    call load_contact
    return
;
; image - browse for an image file
;
image,
    clear g_select
    if (%u_getfilename(inp_contact.image, "Select image file",,,
    &                  ,inp_contact.image))
      begin
        xcall ax_tkset(id_image, "ImagePath", %atrim(inp_contact.image))
      end
    return
;
; update - update the current contact
;
update,
.ifdef D_GUI
    xcall ax_tkget(id_text, "Text", inp_contact.notes)
.else
    xcall w_area(id_text, WA_COPY, WAC_WTOP)
    xcall w_info(WI_XFR, id_text, WIX_DGET, inp_contact.notes)
.endc
    if (inp_contact)
      begin
        if (read_one)
          delete(chan_contacts)
        store(chan_contacts, inp_contact) [dup=duperr, err=write_err]
      end
update_cont,
    ;xcall u_update(FALSE)
    xcall l_restart(id_list, 1, %isinfo(chan_icontacts,"NUMRECS"))
    xcall l_process(id_list, request=D_LFIND, list_contact,,
    &               chan_icontacts)
    clear g_select, read_one
    return
duperr,
    xcall u_msgbox("Duplicate name, changes not saved")
    goto update_cont
write_err,
    xcall u_msgbox("Unable to save changes, error = " + %string(%ernum))
    goto update_cont
endsubroutine
subroutine load_contacts, reentrant
;
; Description:  Load method for contacts list
;
; Arguments:
;
    a_listid     ,n    ;ID of the list
    a_request    ,n    ;List load request
    group a_data ,a    ;Data structure
.include "contact" repository, norecord
    endgroup
    a_inpid      ,n    ;ID of the list's input window
    a_dsa        ,n    ;Item disabled flag
    a_index      ,n    ;Item index
    a_chan       ,n    ;Channel for loading
.align
stack record
    name         ,a35
proc
    if (a_index == 1) then
      read(a_chan, a_data, ^FIRST) [err=eof]
    else
      reads(a_chan, a_data, eof)
    name = a_data.lastname
    if (a_data.firstname)
      name = %atrim(name) + ", " + a_data.firstname
    xcall i_dspfld(a_inpid, "name", name)
    xreturn
eof,            ;EOF encountered
    a_request = D_LEOF
    xreturn
endsubroutine
subroutine arrive_contact    ,reentrant
;
; Description:  List item arrive method for contacts
;
; Arguments:    None used here
;
.include "WND:tools.def"
proc
    if (!g_select)
      xcall m_signal("O_SEL")    ;Select this one.
    xreturn
endsubroutine

subroutine entrst    ,reentrant
;
; Description: EENTRST_METHOD
;
; Arguments:
;
    a_nodata    ,n
    a_reset     ,n
proc
    if (!a_nodata)
      clear a_reset
    xreturn
endsubroutine
function notes_click    ,^val, reentrant
;
; Description:  Stock click event for the notes control
;
; Arguments:
;
    a_ctl    ,i    ;Control ID
.align
stack record
    wndid    ,i4    ;ID of the containing window
proc
    wndid = %ax_getint(a_ctl, D_AXSINGLE_WNDID)    ;Get window ID.
    if (wndid)
      xcall u_wndevents(D_SIGNAL, wndid, D_EVENT_LEFT_CLICK,
      &                 1, 1, 1, 1, 0)
    freturn TRUE
endfunction

The following is the window script for the above example:

.script
.column c_general, "General"
.entry o_exit, "Exit", key(f4), select(x)
.entry c_next, "Next component", key(^n)
.entry c_prev, "Previous component", key(^b)
.end

.input il_contacts, 1, 35
.field name, a35
.end
.listclass l_contacts, header(1), load_method("load_contacts"), ‑
        arrive_method("arrive_contact")
.end
.column c_listsel, "Select"
.entry s_up, "Up", key(up)
.entry s_down, "Down", key(down)
.entry s_top, "First", key(^f)
.entry s_bottom, "Last", key(^l)
.end
.input i_contact, 5, 40
.repository_structure contact
.field firstname, pos(1,1), prompt("First name: "), required, fpos(1,15)
.field lastname, pos(2,1), prompt("Last name: "), fpos(2,15)
.field phone, pos(3,1), prompt("Phone number: "), fpos(3,15)
.field email, pos(4,1), prompt("E-mail: "), fpos(4,15), view_length(25)
.text t1, position(5,1)
Notes:
.end
.column c_input, "Input"
.entry i_nextctl, "Next", key(down)
.entry i_prevctl, "Previous", key(up)
.end
.column c_edit, "Edit"
.entry e_up, "Up", key(up)
.entry e_down, "Down", key(down)
.entry e_left, "Left", key(left)
.entry e_right, "Right", key(right)
.end
.input i_imagebtn, 1, 1
.button o_image, text("Image..."), select('i')
.button_set right(1)
.end

The following is the schema for the repository used in the above example:

Structure CONTACT   DBL ISAM   Modified 20061108152400
   Description "Contacts"
 
Field LASTNAME   Type ALPHA   Size 20
   Description "Contact's last name"
 
Field FIRSTNAME   Type ALPHA   Size 15
   Description "Contact's first name"
 
Field PHONE   Type ALPHA   Size 15
   Description "Contact's phone number"
 
Field EMAIL   Type ALPHA   Size 64
   Description "E-mail address"
 
Field IMAGE   Type ALPHA   Size 256
   Description "Location of picture of contact"
 
Field NOTES   Type ALPHA   Size 1024
   Description "Notes on contact"

DC_ADD

tab_indx = %C_CONTAINER(DC_ADD, container_id, DC_LIST|DC_WINDOW, child_id, [row], [col], [recordindex],
&       [method], [tabindex][, col_id])

Return value

tab_indx

The tabbing index of the child within the composite container window. (n)

Arguments

container_id

The ID of the composite container window. This must be the ID of a composite container window (created with the DC_CREATE subfunction). Any other value will cause a fatal Toolkit error. (n)

DC_LIST | DC_WINDOW

The type of child: DC_LIST for a standard Toolkit list or an ActiveX Toolkit list, or DC_WINDOW for a Toolkit window. (n)

child_id

The ID for an existing window or list to be associated with the container. See the Discussion below. (n)

row

(optional) Placement row for child window or list. See the Discussion below. (n)

col

(optional) Placement column for child window or list. See the Discussion below. (n)

recordindex

(optional) An index that determines which a_methoddata argument passed in C_PROCESS calls will be used as the data record or field to accept input data for the method. (n)

method

(optional) Method for processing the child. See the Discussion below. (a or n)

tabindex

(optional) Tabbing index (base 1) for the child, which enables you to insert the child at any position in the tabbing order.  (n)

col_id

(optional) ID of a menu column to place when processing this child.  (n)

Discussion

The DC_ADD subfunction of %C_CONTAINER adds an existing UI Toolkit window or list to a composite window. DC_ADD can add any type of Toolkit window or list, including an ActiveX window, an ActiveX Toolkit list, a .NET form window, or another composite window. In all cases, the added window or list becomes a child of the composite container window specified with container_id. Note the following:

xcall c_container(DC_ADD, ctrid, chldid, 1, 1)
xcall w_brdr(chldid, WB_SBOFF)

On UNIX and OpenVMS, if a child is too large to fit in its composite container window, the display area is circumscribed to make it fit within the display area of the container window.

Child_id must be the ID of an existing Toolkit window or list. You can add any type of window or list, but the window or list cannot be the child of another container. Additionally, a window or list must be logged with Toolkit environment processing (current, global, or another environment) before it can be added as a child.

Row and col optionally specify the position of the upper left corner of the child window or list. These settings are relative to the composite container window’s client area, so if you pass 1 for row and 1 for col, the child will be placed in the upper left corner of the client area. Additionally, passing these arguments instructs Toolkit to place the child window or list. Omitting one or both of these arguments prevents the child from being placed.

Note

If row is passed, col must also be passed. Attempting to pass row without col will cause a fatal Toolkit error. If row is not passed, the window or list will not be placed and col, if passed, will be ignored.

Recordindex specifies which a_methoddata argument passed in C_PROCESS calls will be passed as the record argument to the processing method for the child. When C_PROCESS calls the method for the child, it passes on all supplied a_methoddata arguments, and it passes as the record argument the a_methoddata argument that corresponds to the recordindex value. (The default methods that use record use it as the data record or field that accepts input for the child. See The composite window processing methods for more information.) In the following, for example, because the value 2 is passed as recordindex in the DC_ADD call, the second a_methoddata argument (data2) in the C_PROCESS call will be passed as the record argument (and as the second a_methoddata argument) to the method for the child. If the method is the default input method (C_METHINP), for example, the value for data2 will be passed as the third argument (data_area) in the I_INPUT call for the method.

xcall c_container(DC_ADD, cnt_id1, DC_WINDOW, input_id, 16, 1, 2)
.
.
.
xcall c_process(cnt_id1, data1, data2)

Note the following for recordindex:

If method is alphanumeric, it specifies the name of a method to invoke to process the child window. If method is numeric and non‑zero, it specifies the address (as returned by %XADDR) of a method to invoke to process the child window.

If you specify a method, the method must be available when the window or list is associated with the container. If method is blank or zero, the default method is used to process the child window or list. See C_PROCESS.

Generally, you’ll want to add child windows and lists to the container in the order that you want users to tab through them. However, you can use tabindex to specify a position (base 1) in the tabbing order. Indices for siblings at or beyond tabindex are incremented by 1.

Col_id, if passed and non‑zero, specifies the ID of a menu column to be loaded when C_PROCESS is called for the container. If g_plc_col_args is true, C_PROCESS places the column prior to invoking a method and removes it after the method returns.

See also

Controlling tabbing, focus, and input context for information on tabbing indices.

DC_BTNFOCUS

old_button = %C_CONTAINER(DC_BTNFOCUS, container_id[, new_button])

or

xcall C_CONTAINER(DC_BTNFOCUS, container_id[, new_button])

Return value

old_button

The tabbing index of the button that has focus when this function is called, or 0 if no button has focus. (n)

Arguments

container_id

The ID of the composite container window. This must be the ID of a composite container window (created with the DC_CREATE subfunction). Any other value will cause a fatal Toolkit error. (n)

new_button

(optional) The index or name of a button that you want to receive focus. (a or n)

Discussion

This subfunction is only supported on Windows.

The DC_BTNFOCUS subfunction of %C_CONTAINER does one or both of the following:

If you pass new_button, and it is not zero or blank, this function does both of the above. Additionally, the context for the container is automatically set to zero (to focus buttons), and the context reason is set to “C_SET”. (See the C_PROCESS Discussion for more information on “C_SET”.) If no further context changes are made, the next call to C_PROCESS moves focus to the specified button.

A non‑blank alphanumeric value is interpreted as a button name. If you pass an alphanumeric value, it must match a button name for the container, or it will cause a fatal Toolkit error. A non‑zero numeric value is interpreted as a button index (base 1). If you pass a non‑zero numeric value, it must match an index for a button on the container, or it will cause a fatal Toolkit error.

If you do not pass new_button (or pass a value of 0 or blank), this function does not set focus to a button, but only indicates (with old_button) whether a button has focus and, if so, returns the tabbing index for that button.

Note

If focus is on a child window or list when you call DC_BTNFOCUS, context for the container is automatically set to 0, but focus will not be set to the specified button until the next call to C_PROCESS. To do this without exiting the current C_PROCESS processing, signal a menu entry, such as “C_RESET”, in the method after the DC_BTNFOCUS call.

On UNIX and OpenVMS, DC_BTNFOCUS does nothing unless new_button is passed. If new_button is passed, DC_BTNFOCUS causes C_PROCESS to process the first child window or list if a button that corresponds to new_button is defined for the window. If new_button does not correspond to any button defined for the window, there is a fatal error.

See also

DC_CHILD

status =   %C_CONTAINER(DC_CHILD, container_id, tabindex, DC_LIST|DC_WINDOW, child_id)

or

xcall C_CONTAINER(DC_CHILD, container_id, tabindex, DC_LIST|DC_WINDOW, child_id)

Return value

status

True if the specified tabbing index (tabindex) exists for the composite window; false if not. (n)

Arguments

container_id

The ID of the composite container window. This must be the ID of a composite container window (created with the DC_CREATE subfunction). Any other value will cause a fatal Toolkit error. (n)

tabindex

The tabbing index for the child window or list. (n)

DC_LIST | DC_WINDOW

The returned child type: DC_LIST for a standard Toolkit list or an ActiveX Toolkit list, or DC_WINDOW for a Toolkit window. (n)

child_id

The returned ID of the child window or list. (n)

Discussion

The DC_CHILD subfunction of %C_CONTAINER indicates whether a child exists for a given tabbing index (tabindex) and, if so, returns the type and ID for the child:

See also

Controlling tabbing, focus, and input context for information on tabbing indices.

DC_CHILDINDEX

tabindex = %C_CONTAINER(DC_CHILDINDEX, container_id, DC_LIST|DC_WINDOW, child_id)

Return value

tabindex

The tabbing index of a child window or list, or 0 if the specified window or list is not a child of this container. (n)

Arguments

container_id

The ID for the composite container window. This must be the ID of a composite container window (created with the DC_CREATE subfunction). Any other value will cause a fatal Toolkit error. (n)

DC_LIST | DC_WINDOW

The type of the child whose tabbing index you want returned: DC_LIST for a standard Toolkit list or an ActiveX Toolkit list, or DC_WINDOW for a Toolkit window. (n)

child_id

The ID of the child window or list. (n)

Discussion

The DC_CHILDINDEX subfunction of %C_CONTAINER enables you to determine if a window or list is a child of a specified container and, if it is, returns its tabbing index.

Pass both the type of child (DC_LIST or DC_WINDOW) and child_id (which must be a valid Toolkit window or list ID) to specify the window or list.

See also

Controlling tabbing, focus, and input context for information on tabbing indices.

DC_CONTAINER

container_id = %C_CONTAINER(DC_CONTAINER, DC_LIST|DC_WINDOW, child_id)

Return value

container_id

The ID of the composite container window for a specified window or list, or 0 if the specified window or list is not part of a composite window. (n)

Arguments

DC_LIST | DC_WINDOW

The type of the child whose container ID you want returned: DC_LIST for a standard Toolkit list or an ActiveX Toolkit list, or DC_WINDOW for a Toolkit window. (n)

child_id

The ID of the child window or list. (n)

Discussion

The DC_CONTAINER subfunction of %C_CONTAINER returns the ID of the composite container window associated with a child or, if the window or list specified by child_id is not a child, indicate this by returning zero. Note that for a composite window within another composite window, DC_CONTAINER returns the ID for the immediate container.

Pass both the type of child (DC_LIST or DC_WINDOW) and child_id (which must be a valid Toolkit window or list ID) to specify the window or list.

DC_CONTEXT

old_context = %C_CONTAINER(DC_CONTEXT, container_id, [new_context][, reason])

or

xcall C_CONTAINER(DC_CONTEXT, container_id, [new_context][, reason])

Return value

old_context

The tabbing index for the child window or list that was active when this function was called, or 0 if one of the buttons on the composite container window was active. (n)

Arguments

container_id

The ID for the composite container window. This must be the ID of a composite container window (created with the DC_CREATE subfunction). Any other value will cause a fatal Toolkit error. (n)

new_context

(optional) The tabbing index for the child window or list that you want to be active, or a value of 0 if you want focus to move to the container, which will have the effect of focusing the first button on the next call to C_PROCESS, or the first child if there is no button. (n)

reason

(optional) The reason for the context change. This can be blank (indicating no change), a program‑supplied reason passed when changing context programmatically, or one of the following: (a)

C_FIRST = Attempt to reach first child.

C_LAST = Attempt to reach last child.

C_NEXT = Context shift from previous child (e.g., tab).

C_PREV = Context shift from next child (e.g., shift+tab).

C_SET = Context explicitly placed on this child (e.g., mouse click or programmatically without a specified reason).

If you pass reason, up to the first 30 characters of this argument are passed to the method for the new active child window or list when the method for that child is invoked.

Discussion

The DC_CONTEXT subfunction of %C_CONTAINER does one or both of the following:

If you do pass new_context, this function does both of the above. If no further context changes are made, the next call to C_PROCESS moves focus to the specified child window or list. Or, if you passed new_context as zero, it moves focus either to the current button for the container (if the container has buttons) or to the first child (if the container does not have buttons). Note, however, that if new_context is passed and is less than zero or greater than the number of children for the container, a fatal Toolkit error will result.

If you do not pass new_context, this function does not make another child window or list active, but only returns the index for the currently active child or returns zero if a button on the container window is active.

See also

DC_CREATE

container_id = %C_CONTAINER(DC_CREATE, name, rows, cols[, title])

Return value

container_id

The ID for the created composite container window. (n)

Arguments

name

A name for the new composite container window. (a)

rows

The number of rows in the container. (n)

cols

The number of columns in the container. (n)

title

(optional) The title for the composite container window. (a)

Discussion

The DC_CREATE subfunction of %C_CONTAINER creates a composite container window, which is a UI Toolkit window that can be associated with other Toolkit windows and lists to create a composite window. Note that when you create a composite container window, it is automatically logged with the current Toolkit environment. You can, however, promote it to global with U_GBLWND.

If you pass a null string (“”) for name, Toolkit assigns a unique name in the form _W_nnn, where nnn is the container ID.

If title is not passed, the container window will not have a title. (You can add one later using the WB_TITLE subfunction of W_BRDR.)

See also

Creating and processing composite windows.

DC_CTRCONTEXT

new_context = %C_CONTAINER(DC_CTRCONTEXT, container_id, reason)

Return value

new_context

The tabbing index for the child window or list that became active as a result of this function, or 0 if focus moves to a button. (n)

Arguments

container_id

The ID for the composite container window. This must be the ID of a composite container window (created with the DC_CREATE subfunction). Any other value will cause a fatal Toolkit error. (n)

reason

The reason for the context change, which determines which child will become active (see the Discussion below). This can be blank (indicating no change), a program‑supplied reason passed when changing context programmatically, or one of the following: (a)

C_FIRST = Attempt to reach first child.

C_LAST = Attempt to reach last child.

C_NEXT = Context shift from previous child (e.g., tab).

C_PREV = Context shift from next child (e.g., shift+tab).

C_SET = Context explicitly placed on a child or button on the composite container window (e.g., mouse click or programmatically without a specified reason).

Discussion

The DC_CTRCONTEXT subfunction of %C_CONTAINER enables you to use the context change reason to activate a child on a composite window. Typically, this routine is used in the method for contained composite windows (see C_METHCTR). You can, however, pass “C_LAST” to move to the last button or child without having to know how many of either one exist in the container:

c_container(DC_CTRCONTEXT, ctrid, "C_LAST")

DC_CTRCONTEXT does one of the following based on the content of reason, which is typically the reason argument passed to the method from C_PROCESS:

DC_ENABLE

old_state = %C_CONTAINER(DC_ENABLE, container_id, tabindex[, new_state])

or

xcall C_CONTAINER(DC_ENABLE, container_id, tabindex[, new_state])

Return value

old_state

1 if the specified child is enabled when this function is called, or 0 if the child window or list is disabled when this function is called. (n)

Arguments

container_id

The ID for the composite container window with a child whose enabled/disabled state you want to query and/or change. This must be the ID of a composite container window (created with the DC_CREATE subfunction). Any other value will cause a fatal Toolkit error. (n)

tabindex

The tabbing index for the child whose enabled/disabled state you want to query and/or change. (n)

new_state

Either a non‑zero value to enable the child window or list or zero to disable the child window or list. (n)

Discussion

The DC_ENABLE subfunction of %C_CONTAINER enables you to enable or disable a child window or list (specified with tabindex). It also returns the state (enabled or disabled) of the child when DC_ENABLE was called (prior to any change made by the call). If a child window or list is disabled, C_PROCESS will not invoke its method, and on Windows mouse clicks will not trigger events for the window or list.

DC_EVENT

return = %C_CONTAINER(DC_EVENT, container_id, tabindex, event, method)

or

xcall C_CONTAINER(DC_EVENT, container_id, tabindex, event, method)

Return value

return

Always returns true. (n)

Arguments

container_id

The ID for the composite container window with a child window or list whose event method extension you want to replace. This must be the ID of a composite container window created with the DC_CREATE subfunction. Any other value will cause a fatal Toolkit error. (n)

tabindex

The tabbing index for the child window or list whose event method extension you want to replace. (n)

event

The code for the event whose method extension will be replaced. One of the following (defined in tools.def): (n)

D_EVENT_LEFT_CLICK

Left mouse button event.

D_EVENT_MIDDLE_CLICK

Middle mouse button event.

D_EVENT_RIGHT_CLICK

Right mouse button event.

D_EVENT_LEFT_DBLCLK

Double‑click left mouse button.

D_EVENT_MIDDLE_DBLCLK

Double‑click middle mouse button.

D_EVENT_RIGHT_DBLCLK

Double‑click right mouse button.

D_EVENT_MOVE

Move window event.

D_EVENT_SIZE

Size window event.

D_EVENT_MINIMIZE

Minimize window event.

D_EVENT_MAXIMIZE

Maximize window event.

D_EVENT_RESTORE

Restore window event.

D_EVENT_SCROLL

Scroll window event.

D_EVENT_CLOSE

Close window event.

method

The name or address for the routine that will replace any automatically registered %UWNDEVENT_METHOD method for the specified event. (a or n)

Discussion

The DC_EVENT subfunction of %C_CONTAINER registers a routine (method) as an extension to the standard method for an event for a child window or list. This replaces any previously registered extension for the event.

The standard method set contains only one method, a left‑click method that sets the context of the container to the clicked child window or list:

You can register an extension for any event, including the left click event. Note the following:

See also

DC_GETEVENT

method_addr = %C_CONTAINER(DC_GETEVENT, container_id, tabindex, event)

Return value

method_addr

The returned method address, or 0 if no routine is registered as the extension for the specified child window / event pair. (D_ADDR)

Arguments

container_id

The ID for the composite container window. This must be the ID of a composite container window (created with the DC_CREATE subfunction). Any other value will cause a fatal Toolkit error. (n)

tabindex

The tabbing index for the child window or list. (n)

event

The code for the event whose method extension address you want to retrieve. One of the following (defined in tools.def): (n)

D_EVENT_LEFT_CLICK

Left mouse button event.

D_EVENT_MIDDLE_CLICK

Middle mouse button event.

D_EVENT_RIGHT_CLICK

Right mouse button event.

D_EVENT_LEFT_DBLCLK

Double‑click left mouse button.

D_EVENT_MIDDLE_DBLCLK

Double‑click middle mouse button.

D_EVENT_RIGHT_DBLCLK

Double‑click right mouse button.

D_EVENT_MOVE

Move window event.

D_EVENT_SIZE

Size window event.

D_EVENT_MINIMIZE

Minimize window event.

D_EVENT_MAXIMIZE

Maximize window event.

D_EVENT_RESTORE

Restore window event.

D_EVENT_SCROLL

Scroll window event.

D_EVENT_CLOSE

Close window event.

Discussion

The DC_GETEVENT subfunction of %C_CONTAINER returns the address for the currently registered extension for an event method for a child window.

See also

DC_NUMCHILD

number = %C_CONTAINER(DC_NUMCHILD, container_id)

Return value

number

The number of child windows and lists associated with a composite container window. If the composite container window has no children, or if the window is not a composite container window, returns value of 0. (n)

Arguments

container_id

The ID for the composite container window. This must be the ID of a composite container window (created with the DC_CREATE subfunction). Any other value will cause a fatal Toolkit error. (n)

Discussion

The DC_NUMCHILD subfunction of %C_CONTAINER returns the number of child windows and lists associated with a composite container window. For a container that is a child of another container, only immediate children are counted.

DC_REMOVE

xcall C_CONTAINER(DC_REMOVE, container_id, tabindex)

Arguments

container_id

The ID for the composite container window. This must be the ID of a composite container window (created with the DC_CREATE subfunction). Any other value will cause a fatal Toolkit error. (n)

tabindex

The tabbing index for the child window or list to be removed. (n)

Discussion

The DC_REMOVE subfunction of %C_CONTAINER removes a child window or list from a composite window by disassociating it from the composite container window.

When a child is removed from its container the following are true:

If tabindex is less than 1 or greater than the number of child windows and lists, a fatal Toolkit error will result.

If %C_CONTAINER is called as a function with DC_REMOVE, it always returns true.

See also

Controlling tabbing, focus, and input context for information on tabbing indices.