Perform composite window operations
|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
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)
Add a child window or list to a composite window.
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)
Determine whether a child exists for a given tabbing index and, if so, return the type and ID of the child.
Determine whether a window or list is a child and, if it is, return the tabbing index for the child.
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.
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.
Create a composite container window.
Set the active child or button based on a code that indicates the reason the container received focus.
Determine if a child window or list is enabled or disabled and/or enable or disable the child window or list.
Register an extension to the standard event methods for a child window or list.
Return the address for a currently registered extension for an event method for a child window or list.
Return the number of children (windows and lists) associated with a composite container window.
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.
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("Email: "), 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 "Email address" Field IMAGE Type ALPHA Size 256 Description "Location of picture of contact" Field NOTES Type ALPHA Size 1024 Description "Notes on contact"
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)
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:
- When a child is added to a composite window, the child’s border is turned off. You can, however, turn it back on with W_BRDR or L_BORDER. See W_BRDR and L_BORDER for more information.
- By default, child windows and lists are enabled for processing. For information on disabling or re-enabling a child, see DC_ENABLE.
- When a window or list is added to a composite window, its %UWNDEVENTS_METHOD set is replaced by one that better handles mouse clicks in composite windows. The previously registered method set, however, will be registered as extensions to the new method set if it does not match the new method set. See the DC_EVENT Discussion for more information.
- On Windows, if a child is too large to fit in its composite container window, Toolkit reduces the child’s display area to fit in the container and adds scroll bars to the child. To prevent scroll bars from being added to the child, either make the container large enough for the display area defined for the child or call W_BRDR with WB_SBOFF for the child after calling DC_ADD. For example:
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.
- When a container is added to a tab set or another container, it may be resized to fit the display area of the container, which affects the amount of space available for subsequently added child windows and lists.
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.
|
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:
- Recordindex is interpreted as an index. Passing a value of 1 as recordindex specifies the first a_methoddata argument in a C_PROCESS call, passing a value of 2 specifies the second, and so forth. If recordindex is not passed, is less than 1, or specifies an a_methoddata argument that is not passed in a C_PROCESS call, the record argument will not be passed to the method.
- Because the record argument is used by only three of the default methods (C_METHINP for input windows, C_METHLST for lists, and C_METHSEL for selection windows), recordindex is required only if one of these methods (or a method you create that requires it) will be invoked for the child.
- The same recordindex value can be passed for more than one method. For instance, you could have two child input windows that operate on different fields within the same data record.
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.
- If you omit tabindex or pass it as zero, Toolkit adds the child at the end of the tabbing order.
- If you pass a value that is less than zero or greater than the number of children in the container plus 1, a fatal Toolkit error is generated.
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
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:
- Indicates whether focus is on a button on the composite container window, and if so, indicates which button has focus. If old_button is returned as a value of 0, no button on the container window has focus. If old_buttton is returned as a non-zero value, that value indicates which button has focus.
- Sets focus to a specified button (new_button) on the composite container window. In this case, old_button returns the index for the button that had focus before this function was called (or a value of 0 if no button had focus).
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.
|
|
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
- I_CTRCONTEXT and I_NEXT routines for information on setting focus on a button for a child window or list
- Controlling tabbing, focus, and input context for information on tabbing indices
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:
- If there is a child window or list for tabindex, the type of the child is returned (DC_LIST or DC_WINDOW), and child_id returns the ID of the child.
- If there is no child window or list for tabindex, type and child_id are returned as 0, and the function returns status as false.
See also
Controlling tabbing, focus, and input context for information on tabbing indices
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
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.
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:
- Indicates which child window or list is active by returning the tabbing index of the active child, or indicates that a button on the composite container window is active by returning a value of 0.
- Makes the child window or list specified by new_context active. Or, if new_context is passed as a value of 0, makes the first button active or the first child active if there is no button.
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
- C_PROCESS routine for information on processing child windows and lists
- Controlling tabbing, focus, and input context for information on tabbing indices
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
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).
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:
- If reason is “C_FIRST” or “C_NEXT”, it moves focus to the first child window or list. If there are buttons but no child windows or lists, it sets focus on the first button for the container.
- If reason is “C_LAST” or “C_PREV”, it moves focus to the last button (if the container has buttons), or the last child window or list (if the container has no buttons).
- If reason is set to any other value (“C_SET”, blank, etc.), focus does not change.
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.
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)
Left mouse button event.
Middle mouse button event.
Right mouse button event.
Double-click left mouse button.
Double-click middle mouse button.
Double-click right mouse button.
Move window event.
Size window event.
Minimize window event.
Maximize window event.
Restore window event.
Scroll window event.
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)
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:
- For an input window, if the left click occurs on a field, drilldown button, or hyperlink prompt within the window, this method sets a state for the window indicating that the field was clicked. Then, when I_INPUT processes the window, context is established on that item, and the click is simulated again (as long as the clicked item is in the current input set, and as long as context has not been changed for that window in the meantime).
- For a list, if the left click occurs on an item, the standard left click method queues a request to select the item. (If the click occurs elsewhere, such as in the header, this method only returns.)
- For a composite container window (a contained container), this method sets the context of the container to the clicked window or list and then signals “C_RESET” to reset focus for all containers.
You can register an extension for any event, including the left click event. Note the following:
- Extension routines must accept the arguments and return a value as specified in %UWNDEVENTS_METHOD.
- If a routine has already been registered for the event, DC_EVENT replaces that routine with the method specified with method.
- When a child window or list is added to a container window, Toolkit automatically registers any %UWNDEVENTS_METHOD methods associated with that window as extensions to the standard method set for the child window. You can use DC_EVENT to replace these extensions.
- If you register an extension for the left click event, the extension is called first, and then the standard left click event is called unless the extension returns a value of 0, in which case it is not invoked.
- The standard left click event won’t do any of the actions listed above if the clicked window is the currently active window in the currently active container (and its parent window, grandparent window, and so forth, are also the active windows in their containers). However, any extension registered with DC_EVENT will be invoked.
See also
- %UWNDEVENTS_METHOD
- Controlling tabbing, focus, and input context for information on tabbing indices
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)
Left mouse button event.
Middle mouse button event.
Right mouse button event.
Double-click left mouse button.
Double-click middle mouse button.
Double-click right mouse button.
Move window event.
Size window event.
Minimize window event.
Maximize window event.
Restore window event.
Scroll window event.
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_EVENT for information on event extensions
- Controlling tabbing, focus, and input context for information on tabbing indices
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.
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:
- The tabbing indices for subsequent children are decremented.
- The child will no longer be placed.
- The child’s border will retain the state it had before the DC_REMOVE call.
- The %UWNDEVENTS_METHOD set for the child will remain as it was before the DC_REMOVE call, but the left click event for child windows or lists will be disabled.
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
