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

FreeBSD Manual Pages

  
 
  

home | help
shape(n)	       Non-rectangular Window Extension		      shape(n)

NAME
       shape - Set/update/query	shaped window information

SYNOPSIS
       package require shape 0.4

       shape option window ?arg	...?

DESCRIPTION
       The shape command is used to manipulate windows so as to	make them have
       non-rectangular shapes.	It also	permits	the querying  of  the  current
       status  of windows to see what shape they have.	The shape can have any
       of several forms, depending on the option argument:

       shape bounds window ?kind?
	      Returns the bounding box of the shape of	window,	 or  an	 empty
	      string  if the window does not currently have a shape set	for it
	      (i.e. it is rectangular.)	 The kind option allows	the  selection
	      of  which	 shape to retrieve the bounding	box of.	 The -bounding
	      option indicates that the	bounding shape of the window is	to  be
	      queried  (the  default.)	 The  -clip  option indicates that the
	      clipping shape of	the window is to be queried.

       shape get window	?kind?
	      Returns a	list of	rectangles describing the shape	of window.  If
	      window  currently	 has no	shape set for it, this command returns
	      the Xserver's current idea of the	rectangular  shape  of	window
	      which  might  or might not be ``sensible''.  The kind option al-
	      lows the selection of which shape	to retrieve the	shape of.  The
	      -bounding	option indicates that the bounding shape of the	window
	      is to be queried (the default.)  The -clip option	indicates that
	      the clipping shape of the	window is to be	queried.

       shape offset window ?kind? xOffset yOffset
	      Moves  the  shape	 of window by xOffset pixels right and yOffset
	      pixels down, relative to the overall position  of	 window.   The
	      contents of window do not	move.

	      The  kind	 option	 allows	 the selection of which	shape to move.
	      The -bounding option indicates that the bounding shape of	window
	      is  to  be  moved.  The -clip option indicates that the clipping
	      shape of window is to be moved.  The -both option	(the  default)
	      moves both the bounding and the clipping shapes of window.

       shape set window	?kind? ?-offset	xOffset	yOffset? sourcekind ?arg ...?
	      Sets  the	 shape	of window to the shape specified by the	source
	      described	by  sourcekind	...,  possibly	pre-offset  by	(xOff-
	      set,yOffset),  much  as  in  the	shape  offset  command.	 Shape
	      sources are described in ``SHAPE SOURCES'' below.

	      The kind option allows the selection of which shape to set.  The
	      -bounding	 option	indicates that the bounding shape of window is
	      to be set.  The -clip option indicates that the  clipping	 shape
	      of  window  is  to  be set.  The -both option (the default) sets
	      both the bounding	and the	clipping shapes	of window.

       shape  update  window  operation	 ?kind?	 ?-offset   xOffset   yOffset?
       sourcekind ?arg ...?
	      Updates  the  shape of window, applying a	shape using set	opera-
	      tion operation.  The shape applied is specified  by  the	source
	      described	by sourcekind ... and is possibly pre-offset by	(xOff-
	      set,yOffset), much  as  in  the  shape  offset  command.	 Shape
	      sources are described in ``SHAPE SOURCES'' below.

	      The kind option allows the selection of which shape to set.  The
	      -bounding	option indicates that the bounding shape of window  is
	      to  be  set.  The	-clip option indicates that the	clipping shape
	      of window	is to be set.  The -both  option  (the	default)  sets
	      both the bounding	and the	clipping shapes	of window.

	      The  following set operations (and unique	abbreviations of them)
	      are supported:

	      set (aliases: :=,	=)
		     The shape specified by the	source becomes	the  shape  of
		     window.

	      union (aliases: +=, ||)
		     The  new  shape of	window consists	of all areas specified
		     in	either the old shape of	window,	or by the source.

	      intersect	(aliases: *=, &&)
		     The new shape of window consists of all  areas  specified
		     in	both the old shape of window, and by the source.

	      subtract (aliases: -=)
		     The  new  shape of	window consists	of all areas specified
		     by	the old	shape of window	that are not specified by  the
		     source.

	      invert (no aliases)
		     The  new  shape of	window consists	of all areas specified
		     by	the source that	are not	specified by the old shape  of
		     window.

       shape version
	      Return  the  version number of the non-rectangular window	exten-
	      sion installed on	the X server that serves the screen that .  is
	      on.   Note that this is not the version number of	the Tcl/Tk ex-
	      tension, which is	reported in the	(global) variables  shape_ver-
	      sion and shape_patchLevel.

	      This returns a dummy value on Windows.

SHAPE SOURCES
       There  are  six types of	shape sources, though they are not universally
       supported:

       bitmap bitmap
	      This uses	the outline of bitmap (which may be any	string accept-
	      able  to	Tk_GetBitmap) as a shape source.  The same information
	      is  supplied  to	operations  involving  bounding	 and  clipping
	      shapes.

	      This operation is	not supported on Windows.

       photo photoImageName
	      This uses	(with a	suitably patched Tk core) the transparency in-
	      formation	from the given photo image (specified using any	string
	      acceptable to Tk_GetPhoto).  The same information	is supplied to
	      operations involving bounding and	clipping shapes.

       rectangles rectangleList
	      This uses	the union of the  rectangles  in  rectangleList	 as  a
	      source of	shape information (the same information	is supplied to
	      operations involving bounding and	clipping shapes).   Each  rec-
	      tangle  is  described  a	list of	four numbers x1, y1, x2	and y2
	      where (x1,y1) is the  top-left  corner  of  the  rectangle,  and
	      (x2,y2) is the bottom-right corner of the	rectangle.

       reset  This  resets  the	shape of the window the	operation is being ap-
	      plied to to a rectangle with the dimensions of the window	(or at
	      least,  the  dimensions  that the	Xserver	thinks that the	window
	      has.)  This operation is only valid as part  of  the  shape  set
	      command.	 It  ought  to	mark the window	as not being shaped at
	      all, but there is	no protocol for	this in	version	1.0 of	the  X
	      non-rectangular window extension,	making it an impossible	opera-
	      tion.

       text string font
	      This uses	an image of string drawn in font as a source of	 shape
	      information  (the	same information is supplied to	operations in-
	      volving bounding and clipping shapes) where font is  any	string
	      acceptable  to  Tk_GetFont.  Note	that only spaces are supported
	      as whitespace characters in string, and that the effects of  us-
	      ing newline and tab characters is	undefined.

	      This operation is	not supported on Windows.

       window window
	      This  uses  window  as  a	 source	of shape information, with the
	      bounding shape of	window being used to supply bounding  informa-
	      tion,  and  the  clipping	 shape	of window being	used to	supply
	      clipping information.

KINDS OF SHAPE
       Every window has	two kinds of shape; their bounding and their  clipping
       shapes.	 The  bounding shape of	a window describes the area covered by
       that window, and	the clipping shape of a	window describes the  part  of
       the  window  occupied  by the contents of that window.  The area	of the
       window contained	in the bounding	area of	the  window  but  not  in  the
       clipping	 area  of the window is	(X) border of the window.  This	border
       is not useful under Tk (which manages all widget	 borders  internally,)
       so  the default kinds that the various operations work on are such that
       read-only operations work by default on the  bounding  shape  (via  the
       -bounding option) and read-write	operations work	by default on both the
       clip and	the bounding shapes (via the -both option.)  The -clip	option
       is unlikely to be useful	in normal operation.

       Windows	only  supports	one  kind  of shape, so	the difference between
       clipping	and bounding regions is	ignored.

CAVEATS
       When setting the	shape of a toplevel window, make sure that you perform
       an update idletasks between the creation	of the toplevel	and applying a
       shape set or shape update operation to it.  This	is because Tk works by
       reparenting  toplevel windows into a (user-invisible) container,	so al-
       lowing the introduction of a menubar to windows without having to alter
       the  internal  dimensions  of the toplevel.  Because this is done on an
       idle handler, you must wait until after that idle handler has  executed
       before  applying	a reshape operation to a toplevel.  Failure to do this
       will result in the reshaped toplevel  being  apparently	encased	 in  a
       toplevel	 window	 that  is  unresponsive	 to  all  events  (like	Expose
       events).	 While no harm is done to the application, this	an undesirable
       effect  that you	probably do not	want in	your application.  Sometime, I
       will have a go at fixing	this.

       This extension can only handle applications that	use a  single  screen,
       or  at  least, it can only handle those that only attempt to use	shaped
       windows on the same screen as . Since this is the vast majority of  all
       applications,  this  should not prove too onerous a restriction for the
       present.	 This might have been fixed.  Need to test...

       Updating	window shapes can be a very expensive operation,  so  you  are
       advised	to  avoid doing	it as much as possible (do not use it as a way
       of doing	animation - it does not	work well.)  Of	course,	if you need to
       change  the  shape, then	do so, but you should try to find ways that do
       it as little as possible	due to it being	an expensive operation.

       Some other X clients can	run far	slower if they have to	interact  with
       shaped  windows.	 The troublemakers are not always the clients that you
       would expect to cause problems.

DEMO PROGRAMS
       All these programs are located in shape0.4/demos.

       dragger.tcl
	      This creates a window that when Mouse Button 1 is	depressed  in,
	      brings  up a coloured cursor that	(partially) changes colour de-
	      pending on whether the cursor is over the	source window or not.

       fancytext.tcl
	      A	fairly simple, but effective, demonstration of how to  make  a
	      simple  piece of text look far more effective using moving lines
	      clipped to the text to suggest the letters without showing  them
	      all at once.

       fingerprint.tcl
	      This  puts a grubby-looking fingerprint on the screen.  The fin-
	      gerprint can be dragged about the	 screen	 (the  cursor  changes
	      when  it	is  possible to	drag the fingerprint).	Thanks to John
	      LoVerso <loverso@opengroup.org> for this little demo!

TO-DO
       I need fix the caveat relating to toplevels and check for  and  resolve
       any  conflicts  with some of the	other capabilities of toplevels	(espe-
       cially the -menu	and -use options).

       I want to write some code to install the	extension.

       I need to test the code for Windows, but	I have no  compiler  that  can
       target  the platform.  Also, anyone who can supply code to convert bit-
       maps or text to regions is welcome to contribute!

       I would like input about	using  non-rectangular	windows	 on  other  Tk
       platforms (notably the Mac.)

       It  would  be rather nice to be able to anchor cutouts to corners/edges
       of a window and have them handle	window	resizes	 correctly.   Possibly
       also a scaling operation	could be added.

       At  some	point, I ought to look into more complex alpha blending, which
       some people report that is supported in a few places.  It does have the
       disadvantage  of	only being able	to work	on systems with	at least 15 or
       16 bits per pixel; 8-bpp	displays (like the ones	I use) simply  do  not
       have the	hardware to cope with this...

       There  are  probably loads of other things that need doing, but I can't
       think of	them right now.

AUTHOR
       Donal K.	Fellows	<fellowsd@cs.man.ac.uk>

KEYWORDS
       shape, window

Shape				      0.4			      shape(n)

NAME | SYNOPSIS | DESCRIPTION | SHAPE SOURCES | KINDS OF SHAPE | CAVEATS | DEMO PROGRAMS | TO-DO | AUTHOR | KEYWORDS

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

home | help