1Tk_CreateWindow(3)           Tk Library Procedures          Tk_CreateWindow(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tk_CreateWindow, Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWin‐
9       dowExist - create or delete window
10

SYNOPSIS

12       #include <tk.h>
13
14       Tk_Window
15       Tk_CreateWindow(interp, parent, name, topLevScreen)
16
17       Tk_Window
18       Tk_CreateAnonymousWindow(interp, parent, topLevScreen)
19
20       Tk_Window
21       Tk_CreateWindowFromPath(interp, tkwin, pathName, topLevScreen)
22
23       Tk_DestroyWindow(tkwin)
24
25       Tk_MakeWindowExist(tkwin)
26

ARGUMENTS

28       Tcl_Interp *interp (out)               Tcl interpreter to use for error
29                                              reporting.   If no error occurs,
30                                              then *interp is not modified.
31
32       Tk_Window parent (in)                  Token for the window that is  to
33                                              serve  as  the logical parent of
34                                              the new window.
35
36       const char *name (in)                  Name to  use  for  this  window.
37                                              Must  be  unique among all chil‐
38                                              dren of the same parent.
39
40       const char *topLevScreen (in)          Has same format  as  screenName.
41                                              If NULL, then new window is cre‐
42                                              ated as an internal window.   If
43                                              non-NULL,  new window is created
44                                              as a top-level window on  screen
45                                              topLevScreen.   If  topLevScreen
46                                              is an empty string (“”) then new
47                                              window  is  created as top-level
48                                              window of parent's screen.
49
50       Tk_Window tkwin (in)                   Token for window.
51
52       const char *pathName (in)              Name of new window, specified as
53                                              path   name  within  application
54                                              (e.g. .a.b.c).
55______________________________________________________________________________
56

DESCRIPTION

58       The procedures Tk_CreateWindow, Tk_CreateAnonymousWindow,  and  Tk_Cre‐
59       ateWindowFromPath  are  used  to create new windows for use in Tk-based
60       applications.  Each of the procedures returns a token that can be  used
61       to manipulate the window in other calls to the Tk library.  If the win‐
62       dow could not be created successfully, then NULL is  returned  and  the
63       result of interpreter interp is modified to hold an error message.
64
65       Tk  supports two different kinds of windows:  internal windows and top-
66       level windows.  An internal window is an interior window of a Tk appli‐
67       cation,  such as a scrollbar or menu bar or button.  A top-level window
68       is one that is created as a child of a  screen's  root  window,  rather
69       than  as an interior window, but which is logically part of some exist‐
70       ing main window.  Examples of top-level windows are  pop-up  menus  and
71       dialog boxes.
72
73       New  windows  may  be  created  by  calling  Tk_CreateWindow.   If  the
74       topLevScreen argument is NULL, then the new window will be an  internal
75       window.   If  topLevScreen  is  non-NULL, then the new window will be a
76       top-level window: topLevScreen indicates the name of a screen  and  the
77       new  window  will  be  created  as  a  child  of  the  root  window  of
78       topLevScreen.  In either case Tk will consider the new window to be the
79       logical  child  of parent: the new window's path name will reflect this
80       fact, options may be specified for the new window  under  this  assump‐
81       tion,  and  so on.  The only difference is that new X window for a top-
82       level window will not be a child of parent's X window.  For example,  a
83       pull-down  menu's parent would be the button-like window used to invoke
84       it, which would in turn be a child of the menu bar  window.   A  dialog
85       box might have the application's main window as its parent.
86
87       Tk_CreateAnonymousWindow  differs  from Tk_CreateWindow in that it cre‐
88       ates an unnamed window.  This window will be manipulatable only using C
89       interfaces, and will not be visible to Tcl scripts.  Both interior win‐
90       dows and top-level windows may be created  with  Tk_CreateAnonymousWin‐
91       dow.
92
93       Tk_CreateWindowFromPath  offers an alternate way of specifying new win‐
94       dows.  In Tk_CreateWindowFromPath the new window is  specified  with  a
95       token  for  any  window  in the target application (tkwin), plus a path
96       name for the new window.  It produces the same effect as  Tk_CreateWin‐
97       dow  and  allows  both  top-level  and  internal windows to be created,
98       depending on the value of  topLevScreen.   In  calls  to  Tk_CreateWin‐
99       dowFromPath, as in calls to Tk_CreateWindow, the parent of the new win‐
100       dow must exist at the time of the call, but the  new  window  must  not
101       already exist.
102
103       The  window  creation procedures do not actually issue the command to X
104       to create a window.  Instead, they create a local data structure  asso‐
105       ciated  with  the  window  and defer the creation of the X window.  The
106       window will actually be created by  the  first  call  to  Tk_MapWindow.
107       Deferred  window creation allows various aspects of the window (such as
108       its size, background color, etc.) to be  modified  after  its  creation
109       without  incurring  any  overhead  in the X server.  When the window is
110       finally mapped all of the window attributes can be set  while  creating
111       the window.
112
113       The  value  returned  by a window-creation procedure is not the X token
114       for the window (it cannot be, since X has not been asked to create  the
115       window  yet).  Instead, it is a token for Tk's local data structure for
116       the window.  Most of the Tk library procedures take  Tk_Window  tokens,
117       rather  than  X  identifiers.   The  actual  X window identifier can be
118       retrieved from the local data structure using  the  Tk_WindowId  macro;
119       see the manual entry for Tk_WindowId for details.
120
121       Tk_DestroyWindow  deletes  a window and all the data structures associ‐
122       ated with it, including any event handlers created with  Tk_CreateEven‐
123       tHandler.   In  addition,  Tk_DestroyWindow will delete any children of
124       tkwin recursively (where children are defined in the Tk sense, consist‐
125       ing  of all windows that were created with the given window as parent).
126       If tkwin is an internal  window,  then  event  handlers  interested  in
127       destroy  events  are  invoked  immediately.  If tkwin is a top-level or
128       main window, then the event handlers will be invoked later, after X has
129       seen the request and returned an event for it.
130
131       If  a  window  has been created but has not been mapped, so no X window
132       exists, it is possible to force the creation of the X window by calling
133       Tk_MakeWindowExist.   This procedure issues the X commands to instanti‐
134       ate the window given by tkwin.
135

KEYWORDS

137       create, deferred creation, destroy, display, internal  window,  screen,
138       top-level window, window
139
140
141
142Tk                                    4.2                   Tk_CreateWindow(3)
Impressum