Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Tk_CreateWindow(3)	     Tk	Library	Procedures	    Tk_CreateWindow(3)

______________________________________________________________________________

NAME
       Tk_CreateWindow,	Tk_CreateWindowFromPath, Tk_DestroyWindow, Tk_MakeWin-
       dowExist	- create or delete window

SYNOPSIS
       #include	<tk.h>

       Tk_Window
       Tk_CreateWindow(interp, parent, name, topLevScreen)

       Tk_Window
       Tk_CreateAnonymousWindow(interp,	parent,	topLevScreen)

       Tk_Window
       Tk_CreateWindowFromPath(interp, tkwin, pathName,	topLevScreen)

       Tk_DestroyWindow(tkwin)

       Tk_MakeWindowExist(tkwin)

ARGUMENTS
       Tcl_Interp *interp (out)		      Tcl interpreter to use for error
					      reporting.   If no error occurs,
					      then *interp is not modified.

       Tk_Window parent	(in)		      Token for	the window that	is  to
					      serve  as	 the logical parent of
					      the new window.

       const char *name	(in)		      Name to  use  for	 this  window.
					      Must  be	unique among all chil-
					      dren of the same parent.

       const char *topLevScreen	(in)	      Has same format  as  screenName.
					      If NULL, then new	window is cre-
					      ated as an internal window.   If
					      non-NULL,	 new window is created
					      as a top-level window on	screen
					      topLevScreen.   If  topLevScreen
					      is an empty string ("") then new
					      window  is  created as top-level
					      window of	parent's screen.

       Tk_Window tkwin (in)		      Token for	window.

       const char *pathName (in)	      Name of new window, specified as
					      path   name  within  application
					      (e.g. .a.b.c).
______________________________________________________________________________

DESCRIPTION
       The procedures Tk_CreateWindow, Tk_CreateAnonymousWindow,  and  Tk_Cre-
       ateWindowFromPath  are  used  to	create new windows for use in Tk-based
       applications.  Each of the procedures returns a token that can be  used
       to manipulate the window	in other calls to the Tk library.  If the win-
       dow could not be	created	successfully, then NULL	is  returned  and  the
       result of interpreter interp is modified	to hold	an error message.

       Tk  supports two	different kinds	of windows:  internal windows and top-
       level windows.  An internal window is an	interior window	of a Tk	appli-
       cation,	such as	a scrollbar or menu bar	or button.  A top-level	window
       is one that is created as a child of a  screen's	 root  window,	rather
       than  as	an interior window, but	which is logically part	of some	exist-
       ing main	window.	 Examples of top-level windows are  pop-up  menus  and
       dialog boxes.

       New  windows  may  be  created  by  calling  Tk_CreateWindow.   If  the
       topLevScreen argument is	NULL, then the new window will be an  internal
       window.	 If  topLevScreen  is  non-NULL, then the new window will be a
       top-level window: topLevScreen indicates	the name of a screen  and  the
       new  window  will  be  created  as  a  child  of	 the  root  window  of
       topLevScreen.  In either	case Tk	will consider the new window to	be the
       logical	child  of parent: the new window's path	name will reflect this
       fact, options may be specified for the new window  under	 this  assump-
       tion,  and  so on.  The only difference is that new X window for	a top-
       level window will not be	a child	of parent's X window.  For example,  a
       pull-down  menu's parent	would be the button-like window	used to	invoke
       it, which would in turn be a child of the menu bar  window.   A	dialog
       box might have the application's	main window as its parent.

       Tk_CreateAnonymousWindow	 differs  from Tk_CreateWindow in that it cre-
       ates an unnamed window.	This window will be manipulatable only using C
       interfaces, and will not	be visible to Tcl scripts.  Both interior win-
       dows and	top-level windows may be created  with	Tk_CreateAnonymousWin-
       dow.

       Tk_CreateWindowFromPath	offers an alternate way	of specifying new win-
       dows.  In Tk_CreateWindowFromPath the new window	is  specified  with  a
       token  for  any	window	in the target application (tkwin), plus	a path
       name for	the new	window.	 It produces the same effect as	 Tk_CreateWin-
       dow  and	 allows	both top-level and internal windows to be created, de-
       pending on the  value  of  topLevScreen.	  In  calls  to	 Tk_CreateWin-
       dowFromPath, as in calls	to Tk_CreateWindow, the	parent of the new win-
       dow must	exist at the time of the call, but the new window must not al-
       ready exist.

       The  window  creation procedures	do not actually	issue the command to X
       to create a window.  Instead, they create a local data structure	 asso-
       ciated  with  the  window  and defer the	creation of the	X window.  The
       window will actually be created by the first call to Tk_MapWindow.  De-
       ferred  window  creation	 allows	various	aspects	of the window (such as
       its size, background color, etc.) to be	modified  after	 its  creation
       without incurring any overhead in the X server.	When the window	is fi-
       nally mapped all	of the window attributes can be	set while creating the
       window.

       The  value  returned  by	a window-creation procedure is not the X token
       for the window (it cannot be, since X has not been asked	to create  the
       window  yet).  Instead, it is a token for Tk's local data structure for
       the window.  Most of the	Tk library procedures take  Tk_Window  tokens,
       rather  than  X identifiers.  The actual	X window identifier can	be re-
       trieved from the	local data structure using the Tk_WindowId macro;  see
       the manual entry	for Tk_WindowId	for details.

       Tk_DestroyWindow	 deletes  a window and all the data structures associ-
       ated with it, including any event handlers created with	Tk_CreateEven-
       tHandler.   In  addition,  Tk_DestroyWindow will	delete any children of
       tkwin recursively (where	children are defined in	the Tk sense, consist-
       ing  of all windows that	were created with the given window as parent).
       If tkwin	is an internal window, then event handlers interested  in  de-
       stroy  events are invoked immediately.  If tkwin	is a top-level or main
       window, then the	event handlers will be invoked later, after X has seen
       the request and returned	an event for it.

       If  a  window  has been created but has not been	mapped,	so no X	window
       exists, it is possible to force the creation of the X window by calling
       Tk_MakeWindowExist.   This procedure issues the X commands to instanti-
       ate the window given by tkwin.

KEYWORDS
       create, deferred	creation, destroy, display, internal  window,  screen,
       top-level window, window

Tk				      4.2		    Tk_CreateWindow(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk_CreateWindow.tk86&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help