*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> Tk/crtmainwin (3)              


Tk_CreateMainWindow(3Tk)			      Tk_CreateMainWindow(3Tk)

NAME    [Toc]    [Back]

     Tk_CreateMainWindow, Tk_CreateWindow, Tk_CreateWindowFromPath,
     Tk_DestroyWindow, Tk_MakeWindowExist - create or delete window

SYNOPSIS    [Toc]    [Back]

     #include <tk.h>

     Tk_CreateMainWindow(interp, screenName, baseName, className)

     Tk_CreateWindow(interp, parent, name, topLevScreen)

     Tk_CreateWindowFromPath(interp, tkwin, pathName, topLevScreen)



ARGUMENTS    [Toc]    [Back]

     Tcl_Interp	  *interp	  (out)	    Tcl	interpreter to use for error
					    reporting.	If no error occurs,
					    then *interp isn't modified.  For
					    Tk_CreateMainWindow, this
					    interpreter	is associated
					    permanently	with the created
					    window, and	Tk-related commands
					    are	bound into the interpreter.

     char	  *screenName	  (in)	    String name	of screen on which to
					    create window.  Has	the form
					    displayName.screenNum, where
					    displayName	is the name of a
					    display and	screenNum is a screen
					    number.  If	the dot	and screenNum
					    are	omitted, the screen number
					    defaults to	0.  If screenName is
					    NULL or empty string, defaults to
					    contents of	DISPLAY	environment

     char	  *baseName	  (in)	    Name to use	for this main window.
					    See	below for details.

     char	  *className	  (in)	    Class to use for application and
					    for	main window.

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

									Page 1

Tk_CreateMainWindow(3Tk)			      Tk_CreateMainWindow(3Tk)

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

     char	  *topLevScreen	  (in)	    Has	same format as screenName.  If
					    NULL, then new window is created
					    as an internal window.  If nonNULL,
 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.

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

DESCRIPTION    [Toc]    [Back]

     The three procedures Tk_CreateMainWindow, Tk_CreateWindow,	and
     Tk_CreateWindowFromPath are used to create	new windows for	use in Tkbased
 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
     window couldn't be	created	successfully, then NULL	is returned and
     interp->result is modified	to hold	an error message.

     Tk	supports three different kinds of windows:  main windows, internal
     windows, and top-level windows.  A	main window is the outermost window
     corresponding to an application.  Main windows correspond to the
     independent units of an application, such as a view on a file that	is
     part of an	editor,	or a clock, or a terminal emulator.  A main window is
     created as	a child	of the root window of the screen indicated by the
     screenName.  Each main window, and	all its	descendants, are typically
     associated	with a single Tcl command interpreter.	An internal window is
     an	interior window	of a Tk	application, 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 existing main window.  Examples of top-level
     windows are pop-up	menus and dialog boxes.

     Tk_CreateMainWindow creates a new main window and associates its interp
     argument with that	window and all its eventual descendants.
     Tk_CreateMainWindow also carries out several other	actions	to set up the
     new application.  First, it adds all the Tk commands to those already
     defined for interp.  Second, it turns the new window into a toplevel
     widget, which will	cause the X window to be created and mapped as soon as
     the application goes idle.	 Third,	Tk_CreateMainWindow registers interp
     so	that it	can be accessed	remotely by other Tk applications using	the
     send command and the name baseName.  Normally, baseName consists of the

									Page 2

Tk_CreateMainWindow(3Tk)			      Tk_CreateMainWindow(3Tk)

     name of the application followed by a space and an	identifier for this
     particular	main window (if	such an	identifier is relevant).  For example,
     an	editor named mx	displaying the file foo.c would	use ``mx foo.c'' as
     the basename.  An application that	doesn't	usually	have multiple
     instances,	such as	a clock	program, would just use	the name of the
     application, e.g. ``xclock''.  If baseName	is already in use by some
     other registered interpreter, then	Tk_CreateMainWindow extends baseName
     with a number to produce a	unique name like ``mx foo.c #2'' or ``xclock
     #12''.  This name is used both as the name	of the window (returned	by
     Tk_Name) and as the registered name of the	interpreter.  Fourth,
     Tk_CreateMainWindow sets className	as the class of	the application	(among
     other things, this	is used	for lookups in the option database), and also
     as	the class of the main widget.

     Either internal or	top-level 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
     assumption, 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.  This approach
     means that	all the	windows	of an application fall into a hierarchical
     arrangement with a	single logical root:  the application's	main window.

     Tk_CreateWindowFromPath offers an alternate way of	specifying new
     windows.  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_CreateWindow and
     allows both top-level and internal	windows	to be created, depending on
     the value of topLevScreen.	 In calls to Tk_CreateWindowFromPath, as in
     calls to Tk_CreateWindow, the parent of the new window must exist at the
     time of the call, but the new window must not already exist.

     In	truth, the window-creation procedures don't actually issue the command
     to	X to create a window.  Instead,	they create a local data structure
     associated	with the window	and defer the creation of the X	window.	 The
     window will actually be created by	the first call to Tk_MapWindow.
     Deferred 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
     finally mapped all	of the window attributes can be	set while creating the

     The value returned	by a window-creation procedure is not the X token for
     the window	(it can't be, since X hasn't been asked	to create the window
     yet).  Instead, it	is a token for Tk's local data structure for the

									Page 3

Tk_CreateMainWindow(3Tk)			      Tk_CreateMainWindow(3Tk)

     window.  Most of the Tk library procedures	take Tk_Window tokens, rather
     than X identifiers.  The actual X window identifier can be	retrieved 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 associated
     with it, including	any event handlers created with	Tk_CreateEventHandler.
     In	addition, Tk_DestroyWindow will	delete any children of tkwin
     recursively (where	children are defined in	the Tk sense, consisting of
     all windows that were created with	the given window as parent).  If tkwin
     was created by Tk_CreateInternalWindow then event handlers	interested in
     destroy 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 hasn't 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 instantiate
     the window	given by tkwin.

KEYWORDS    [Toc]    [Back]

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

									PPPPaaaaggggeeee 4444
[ Back ]
 Similar pages
Name OS Title
menu_new NetBSD create or delete a menu
krb5_init_context NetBSD create and delete krb5_context structures
krb5_free_context FreeBSD create and delete krb5_context structures
crtinterp IRIX create and delete Tcl command interpreters
krb5_free_context OpenBSD create and delete krb5_context structures
krb5_init_context FreeBSD create and delete krb5_context structures
krb5_free_context NetBSD create and delete krb5_context structures
krb5_init_context OpenBSD create and delete krb5_context structures
menu_item_new NetBSD create or delete menu item
curs_delch IRIX delete character under cursor in a curses window
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service