HelpSource/Classes/Window.schelp

   1 CLASS:: Window
   2 redirect:: implClass
   3 summary:: Top-level container of views
   4 categories:: GUI>Views
   5
   6 DESCRIPTION::
   7
   8 The Window is the most fundamental element of the GUI. It occupies a rectangular space on the screen within which other GUI elements (Views) are displayed.
   9
  10 A child view is added into a window by passing the window to the view's constructor. See link::Classes/View#*new::.
  11
  12 note::
  13 In strong::Qt GUI:: there is no distinction between windows, views, and containers; a View can be displayed directly on screen, and can contain other views. Therefore, visual descriptions of Window and most of the methods that are specific to Window in other GUI kits, also apply to and make part of View in Qt, and are thus shared by all its subclasses.
  14
  15 The Window class is provided in Qt GUI for compatibility as well as convenience: e.g. unlike View, Window will be created by default in the center of the screen, and various aspects can be conveniently controlled using its constructor arguments.
  16 ::
  17
  18 The Window is usually drawn with a bar on its top edge that displays the window's title which you can set in the link::#*new#constructor::, or using link::#-name::.
  19
  20
  21
  22 CLASSMETHODS::
  23
  24 PRIVATE:: key
  25
  26 METHOD:: new
  27
  28         Creates a new Window instance. You will need to call link::#-front:: on it to become visible.
  29
  30         argument:: name
  31                 A String for the text that will be displayed in the title bar. The default is 'panel'.
  32         argument:: bounds
  33                 A Rect specifying position and size of the window. The size does not include the border and title bar. Position is measured from the bottom-left corner of the screen (this is different than link::Classes/View#-bounds::). The default is size 400x400 at position 128x64, but in Qt the window is centered on the screen by default.
  34         argument:: resizable
  35                 A Boolean indicating whether this window is resizable by the user. The default is code::true::.
  36         argument:: border
  37                 A Boolean indicating whether this window has a border. Borderless windows have no title bar and thus can only be closed in code. The default is code::true::.
  38         argument:: server
  39                 This is a dummy argument which is here to provide compatibility with SwingOSC and has no effect.
  40         argument:: scroll
  41                 A Boolean indicating whether this window will add scrollbars if its contents exceed its bounds. If this is set to code::true::, then link::Classes/View#-resize:: settings will be ignored for contained views. The default is false.
  42
  43 METHOD:: allWindows
  44
  45         An array of all existing Window instances.
  46
  47 METHOD:: closeAll
  48
  49         Calls link::#-close:: an all existing Window instances.
  50
  51 METHOD:: initAction
  52
  53         The default action object to be evaluated whenever a new Window is instantiated.
  54
  55 METHOD:: screenBounds
  56
  57         Returns a Rect with the size of the screen in pixels
  58
  59 METHOD:: availableBounds
  60
  61         Returns a Rect describing the area of the screen that windows can actually occupy (i.e. excluding the Mac dock, the task bar, or similar).
  62
  63
  64
  65
  66 INSTANCEMETHODS::
  67
  68 SUBSECTION:: View hierarchy
  69
  70 METHOD:: view
  71         When a Window is created, it creates a container view, accessible using this method, that occupies the whole area of the window, and which will be used as the actual parent of the child widgets.
  72
  73         returns::
  74                 A View.
  75
  76 METHOD:: asView
  77         Equivalent to link::#-view::
  78
  79 METHOD:: currentSheet
  80         note:: Only in Cocoa GUI ::
  81         returns:
  82                 The current modal sheet attached to this window, if it exists. See link::Classes/SCModalSheet::.
  83
  84
  85
  86
  87 SUBSECTION:: Visibility
  88
  89 METHOD:: front
  90         Displays the window on the screen (In Qt GUI this has the same effect as setting link::#-visible:: to true).
  91
  92 METHOD:: minimize
  93         Hides the window, only keeping its representation in the dock, taskbar, etc..
  94
  95 METHOD:: unminimize
  96         Restores the window's previous state after being minimized.
  97
  98 METHOD:: fullScreen
  99         Displays the window full-screen.
 100
 101 METHOD:: endFullScreen
 102         Restores the window's previous state after being displayed full-screen.
 103
 104 METHOD:: alwaysOnTop
 105         Whether the window should always stay on top of other windows, even when it is not the active one.
 106
 107         argument::
 108                 A Boolean.
 109
 110 METHOD:: visible
 111         note:: only in Qt GUI ::
 112
 113         Wether the window is visible.
 114
 115         Setting this to code::true:: has the same effect as link::#-front::, and setting it to false closes the window without destroying it.
 116
 117         argument::
 118                 A Boolean.
 119
 120 METHOD:: close
 121
 122         Closes and destroys the window.
 123
 124 METHOD:: isClosed
 125         returns:: A Boolean stating whether the view has been closed.
 126
 127
 128
 129
 130 SUBSECTION:: Geometry
 131
 132 METHOD:: bounds
 133
 134         The position and size of the window. The position is relative to the bottom-left corner of the screen.
 135
 136         argument::
 137                 A Rect or a Point interpreted link::Classes/Point#-asRect#as Rect::.
 138         returns::
 139                 A Rect.
 140
 141 METHOD:: setTopLeftBounds
 142
 143         A convenience method that, unlike link::#-bounds::, sets the bounds by measuring position from the top-left corner of the screen, and vertically offset by code::menuSpacer::.
 144
 145         argument:: rect
 146                 A Rect.
 147         argument:: menuSpacer
 148                 An Integer amount of pixels.
 149
 150 METHOD:: setInnerExtent
 151
 152         Resizes the window, keeping its position intact.
 153
 154         In strong:: Qt GUI ::, this is equivalent to link::Classes/View#-resizeTo:: called on the link::#-view::.
 155
 156         argument:: w
 157                 An Integer width in pixels.
 158         argument:: h
 159                 An Integer height in pixels.
 160
 161 METHOD:: sizeHint
 162         note:: only in Qt GUI ::
 163         Redirects to link::Classes/View#-sizeHint:: of the link::#-view::.
 164
 165 METHOD:: minSizeHint
 166         note:: only in Qt GUI ::
 167         Redirects to link::Classes/View#-minSizeHint:: of the link::#-view::.
 168
 169 METHOD:: addFlowLayout
 170
 171         A convenience method which sets code::decorator:: of the link::#-view:: to a new instance of FlowLayout. See link::Classes/FlowLayout:: for examples.
 172
 173         argument:: margin
 174                 A Point describing the link::Classes/FlowLayout#-margin#margin:: of the FlowLayout.
 175
 176         argument:: gap
 177                 A Point describing the link::Classes/FlowLayout#-gap#gap:: of the FlowLayout.
 178
 179         returns:: The new FlowLayout instance.
 180
 181 METHOD:: layout
 182         note:: only in Qt GUI ::
 183         Redirects to link::Classes/View#-layout:: of the link::#-view::.
 184
 185
 186
 187 SUBSECTION:: Appearance
 188
 189 METHOD:: name
 190         The title of the window.
 191
 192         argument::
 193                 A String.
 194
 195 METHOD:: background
 196         The background color of the window.
 197
 198         argument::
 199                 A Color.
 200
 201 METHOD:: alpha
 202         The transparancy of the window.
 203
 204         argument::
 205                 A Float between 0.0 (invisible) and 1.0 (opaque).
 206
 207 METHOD:: refresh
 208         Redraws the window and all its children.
 209
 210
 211
 212 SUBSECTION:: Interaction
 213
 214 METHOD:: userCanClose
 215         Whether the user can close the window. The default is code::true::.
 216
 217         argument::
 218                 A Boolean.
 219
 220 METHOD:: acceptsClickThrough
 221         Whether the window receives clicks when it is not front-most. The default is code::true::.
 222
 223         argument::
 224                 A Boolean.
 225
 226 METHOD:: acceptsMouseOver
 227         Whether the window receives mouse-over events. The default is code::false::.
 228
 229         argument::
 230                 A Boolean.
 231
 232
 233
 234 SUBSECTION:: Actions and hooks
 235
 236 METHOD:: drawFunc
 237         Just like the link::Classes/UserView::, the window can be given a Function to evalute whenever it is asked to redraw itself, so you can use the link::Classes/Pen:: class to draw on the window. See link::Classes/UserView#-drawFunc:: for explanation.
 238
 239         argument::
 240                 A Function.
 241
 242 METHOD:: toFrontAction
 243
 244         The action object to be evaluated whenever the window becomes the active one.
 245
 246 METHOD:: endFrontAction
 247
 248         The action object to be evaluated whenever the window ceases to be the active one.
 249
 250 METHOD:: onClose
 251
 252         The action object to be evaluated when the window is closed.
 253
 254 METHOD:: addToOnClose
 255
 256         Adds an object to link::#-onClose::, wrapping the current value into an Array, if it is not yet.
 257
 258 METHOD:: removeFromOnClose
 259
 260         Removes an object from link::#-onClose::, if the latter is an Array.