Autodocs
Libraries:
intuition.library
ActivateGadget
ActivateWindow
AddClass
AddGList
AddGadget
AllocRemember
AllocScreenBuffer
AutoRequest
BeginRefresh
BuildEasyRequestArgs
BuildSysRequest
ChangeScreenBuffer
ChangeWindowBox
ClearDMRequest
ClearMenuStrip
ClearPointer
CloseScreen
CloseWindow
CloseWorkBench
CurrentTime
DisplayAlert
DisplayBeep
DisposeObject
DoGadgetMethodA
DoubleClick
DrawBorder
DrawImage
DrawImageState
EasyRequestArgs
EndRefresh
EndRequest
EraseImage
FreeClass
FreeRemember
FreeScreenBuffer
FreeScreenDrawInfo
FreeSysRequest
GadgetMouse
GetAttr
GetDefPrefs
GetDefaultPubScreen
GetPrefs
GetScreenData
GetScreenDrawInfo
HelpControl
InitRequester
IntuiTextLength
ItemAddress
LendMenus
LockIBase
LockPubScreen
LockPubScreenList
MakeClass
MakeScreen
ModifyIDCMP
ModifyProp
MoveScreen
MoveWindow
MoveWindowInFrontOf
NewModifyProp
NewObject
NextObject
NextPubScreen
ObtainGIRPort
OffGadget
OffMenu
OnGadget
OnMenu
OpenScreen
OpenScreenTagList
OpenWindow
OpenWindowTagList
OpenWorkBench
PointInImage
PrintIText
PubScreenStatus
QueryOverscan
RefreshGList
RefreshGadgets
RefreshWindowFrame
ReleaseGIRPort
RemakeDisplay
RemoveClass
RemoveGList
RemoveGadget
ReportMouse
Request
ResetMenuStrip
RethinkDisplay
ScreenDepth
ScreenPosition
ScreenToBack
ScreenToFront
ScrollWindowRaster
SetAttrsA
SetDMRequest
SetDefaultPubScreen
SetEditHook
SetGadgetAttrsA
SetMenuStrip
SetMouseQueue
SetPointer
SetPrefs
SetPubScreenModes
SetWindowPointerA
SetWindowTitles
ShowTitle
SizeWindow
SysReqHandler
TimedDisplayAlert
UnlockIBase
UnlockPubScreen
UnlockPubScreenList
ViewAddress
ViewPortAddress
WBenchToBack
WBenchToFront
WindowLimits
WindowToBack
WindowToFront
ZipWindow
Include
GuruMeditation
|
Docs » Autodocs » intuition.library » BeginRefresh
BeginRefresh -- Sets up a window for optimized refreshing.
BeginRefresh( Window )
A0
VOID BeginRefresh( struct Window * );
This routine sets up your window for optimized refreshing.
Its role is to provide Intuition integrated access to the Layers
library function BeginUpdate(). Its additional contribution is
to be sure that locking protocols for layers are followed, by
locking both layers of a WFLG_GIMMEZEROZERO window only after the
parent Layer_Info has been locked. Also, the WFLG_WINDOWREFRESH
flag is set in your window, for your information.
The purpose of BeginUpdate(), and hence BeginRefresh(), is to
restrict rendering in a window (layer) to the region that needs
refreshing after an operation such as window sizing or uncovering.
This restriction to the "damage region" persists until you call
EndRefresh().
For instance, if you have a WFLG_SIMPLE_REFRESH window which is
partially concealed and the user brings it to the front, you can
receive an IDCMP_REFRESHWINDOW message asking you to refresh your
display. If you call BeginRefresh() before doing any of the
rendering, then the layer that underlies your window will be arranged
so that the only rendering that will actually take place will be that
which goes to the newly-revealed areas. This is very performance-
efficient, and visually attractive.
After you have performed your refresh of the display, you should call
EndRefresh() to reset the state of the layer and the window. Then you
may proceed with rendering to the entire window as usual.
You learn that your window needs refreshing by receiving either a
message of class IDCMP_REFRESHWINDOW through the IDCMP, or an input
event of class IECLASS_REFRESHWINDOW through the Console device.
Whenever you are told that your window needs refreshing, you should
call BeginRefresh() and EndRefresh() to clear the refresh-needed
state, even if you don't plan on doing any rendering. You may relieve
yourself of even this burden by setting the WFLG_NOCAREREFRESH flag
when opening your window.
WARNING: You should only perform simple graphics refreshing
operations between BeginRefresh() and EndRefresh(). These include
any graphics.library drawing functions or the simple Intuition
rendering functions (DrawImage(), PrintIText(), DrawBorder(), and
so on). In particular, do not call RefreshGadgets(), RefreshGList(),
RefreshWindowFrame(), etc., since any of the complex Intuition
functions run the risk of creating a deadlock. Also avoid any
other high-level calls in Intuition or ones that might invoke
Intuition. This means no calling SetPointer(), no calling
LockIBase(), no dos.library functions (since an EasyRequest()
might result), etc. Keep it simple.
By the time the application receives its IDCMP_REFRESHWINDWOW
message, Intuition has already repaired any damaged regions
of the window border or the gadgets in the window, so attempts
to redraw gadgets or borders are as unnecessary as they are
dangerous.
ANOTHER WARNING: The concept of multiple refresh passes using
EndRefresh( w, FALSE ) is not completely sound without further
protection. The reason is that between two sessions, more
damage can occur to your window. Your final EndRefresh( w, TRUE )
will dispose of all damage, including the new, and your
initial refreshing pass will never get the chance to refresh
the new damage.
To avoid this, you must protect your session using LockLayerInfo()
which will prevent Intuition from performing window operations
or anything else which might cause further damage from occurring.
Again, while holding the LayerInfo lock make no Intuition
function calls dealing with gadgets; just render.
You can, however, call InstallClipRegion() for the different
refresh passes, if you have two clip regions.
SIMILAR WARNING: Your program and Intuition "share" your window
layer's DamageList. BeginRefresh() helps arbitrate this
sharing, but the lower-level function layers.library/BeginUpdate()
does not. It isn't really supported to use BeginUpdate() on
a window's layer, but if you do--for whatever reason--it is
critical that you first acquire the LayerInfo lock as in
the above example: even if you only have one pass of refresh
rendering to do. Otherwise, the refreshing of your window's
borders and gadgets can be incomplete, and the problem might
occur only under certain conditions of task priority and
system load.
Code fragment for "two pass" window refreshing, in response
to an IDCMP_REFRESHWINDOW message:
switch ( imsg->Class )
{
...
case IDCMP_REFRESHWINDOW:
window = imsg->IDCMPWindow;
/* this lock only needed for "two-pass" refreshing */
LockLayerInfo( &window->WScreen->LayerInfo );
/* refresh pass for region 1 */
origclip = InstallClipRegion( window->WLayer, region1 );
BeginRefresh( window );
myRefreshRegion1( window );
EndRefresh( window, FALSE );
/* refresh pass for region 2 */
InstallClipRegion( window->WLayer, region2 );
BeginRefresh( window );
myRefreshRegion2( window );
EndRefresh( window, TRUE ); /* and dispose damage list */
/* restore and unlock */
InstallClipRegion( window->WLayer, origclip );
UnlockLayerInfo( &window->WScreen->LayerInfo );
break;
...
}
Window = pointer to the window structure which needs refreshing
None
This function should check the return code of
layers.library/BeginUpdate(), and abort if that function fails.
EndRefresh(), layers.library/BeginUpdate(), OpenWindow(), layer.library/InstallClipRegion, layers.library/LockLayerInfo(), The "Windows" chapter of the Intuition Reference Manual
|
