corz.org text viewer..
[currently viewing: /public/machine/source/windows/AutoIt Includes/corz_gui_fx.au3 - raw]
[currently viewing: /public/machine/source/windows/AutoIt Includes/corz_gui_fx.au3 - raw]
click here for plain text
click here for more groovy stuff like this
; feel free to tap into this in your apps, I do.
#cs
corz gui window animation effects v0.2
functions to simplify window open/close animations
(c) corz.org 2007
function list..
[see the functions themselves for more detailed usage instructions]
corz_GUIAnimateOpen( [window handle[, string/array{animation codes}[, string{ini file path}[, string{ini section}]]]])
corz_GUIAnimateClose( [window handle[, string/array{animation codes}[, string{ini file path}[, string{ini section}]]]])
corz_GUIFadeIn( window handle )
corz_GUIFadeOut( window handle )
corz_GUIGetFX( [string{fx setting} [, string{path to ini file} [, string{ini section} [, string{ini key}]]]])
[private] corz_ValidateFXCodes( string/array{animation codes}[, string{ini file path}[, string{ini section}]]])
In most cases, you will only need to interact with the two main functions:
corz_GUIAnimateOpen() and corz_GUIAnimateClose(). They will access the other
functions in the background, saving and restoring settings to and from your
specified ini file, performing the desired window animations, and so on.
You can also interact directly and easily with corz_GUIFadeIn() and
corz_GUIFadeOut(), and even corz_GUIGetFX(), if you feel the need.
; The functions..
;
corz_GUIAnimateOpen()
Animate the opening of a window.
Feed it the window handle and (optionally) some animation codes (which can
be a simple string, like "slide right" - which means it slide out of the
right hand side). Optionally feed it the path to your ini file, and the
section of that ini to use for (re)storing settings..
corz_GUIAnimateOpen( [window handle[, string/array{animation string/codes}[, string{path to ini} [, string{section name}]]]])
Simplest usage..
corz_GUIAnimateOpen($my_gui)
Which is the same as..
corz_GUIAnimateOpen($my_gui, "Slide Right")
"Slide Right" being the default gui animation (remember, it was designed for
wee tools, that most often, at least on my system, find themselves in the
far-right corners).
corz_GUIAnimateOpen($my_gui, "Slide Top Right")
Is also nice.
Available animation strings..
[strings are case-insensitive; supplied strings & their case are retained in your ini]
To fade in/out use: "fade" ; note, this doesn't use a dll call.
To Slide in & out from the left use: "slide left", "left", "Slide L", or "L"
To Slide in & out from the right use: "slide right", "right", "Slide R", "Slide", or "R" (default fx)
To Slide in & out from the top use: "slide top", "Slide T", "Top", or "T"
To Slide in & out from the bottom use: "slide bottom", "Slide B", "Bottom", or "B"
To Slide in & out from the top-left use: "Slide Top Left", "Top Left", "top-left", "tl", "diagonal tl", "d"
To Slide in & out from the top-right use: "Slide Top Right", "Top Right", "top-right", "tr", "diagonal tr"
To Slide in & out from the bottom-right use: "Slide Bottom Right", "Bottom Right", "bottom-right", "br", "diagonal br"
To Slide in & out from the bottom-left use: "Slide Bottom Left", "Bottom Left", "bottom-left", "bl", "diagonal bl"
To Explode/implode use : "explode/implode", "Explode", "Implode", or "X"
To Disable Window Animation FX use: "Disable window animation", "Disabled", or "-"
If you want your user's animation settings to be stored and retrieved
between launches, but don't want to write the code for that, simply supply
the optional 3rd and 4th parameters; the full path to an ini file, and the
name of the section within that file..
corz_GUIAnimateOpen($my_gui, "bottom", "test.ini", "my fx")
Which will open the window, sliding it up from the bottom, and save this
preference to "test.ini", in the section [fx]. It's no problem to use
your main ini section, in that case a key named "gui_fx" will be written
with the current animation string.
If you want to save some animation setting, but not actually animate the
window (for instance, when a user selects a preference from a menu), simply
send an empty string for the window handle, and specify some valid ini
parameters..
corz_GUIAnimateOpen("", "bottom", "test.ini", "my fx")
It's slightly non-standard, I know, but it saves you ever having to interact
with corz_GUIGetFX() directly, which I thought you might like.
Used in this manner, corz_GUIAnimateOpen() will return valid animation
codes, which you may or may not wish to use later. See corz_GUIGetFX()
for a larger explanation of how these codes might be used. One reason why
you might use these codes is that they are slightly faster to operate.
GUI fx doesn't create any global variables*, so it's a good idea to make
$my_codes (or whatever you call it) global in your application, available
for whenever you need to animate a window.
You will probably want to do that when you first initialize your
window..
global $my_codes = corz_GUIAnimateOpen($my_gui, "", $ini_path, $ini_section)
If the animation string is left blank "", settings will be retrieved from
the ini file, if one is specified (and created if not). In either case,
corz_GUIAnimateOpen() will return the valid animation codes for later use.
If the ini's gui_fx string is invalid or simply doesn't exist, or you
didn't specify valid ini paramters, the default setting will be applied.
As well as returning the valid animation codes array, corz_GUIAnimateOpen()
sets an environment variable (the name of the current "gui_fx" setting) to
the simple string version of the animation setting, as saved in the ini
file. You can use this to set menu selections, checkbox items, or whatever.
GUICtrlSetData($combo, EnvGet('gui_fx'))
Although it's usually 'gui_fx', you may have multiple window animations
running concurrently, so it could be something else. See corz_GUIGetFX() for
details on how to override this value. Note: these environment variable are
destroyed when you quit the application.
Whatever happens, if you specify valid ini parameters, corz_GUIAnimateOpen()
will attempt to save the current setting to the specified ini at the end of
its operation.
Usage examples..
Retrieve saved setting from the ini, and animate the window using those
setting. This is most useful when the application first launches..
corz_GUIAnimateOpen($my_gui, "", "test.ini", "my fx")
Save the setting "Slide Top" to the ini file, perform no animation. This is
most useful when the user selects a preference from a menu or some other
selector..
corz_GUIAnimateOpen("", "Slide Top", "test.ini", "my fx")
"Slide Top" could come from anywhere..
corz_GUIAnimateOpen("", TrayItemGetText(@TRAY_ID), $ini_path, $my_app)
Open the window, animating it up from the bottom, and save that setting
to the ini file. Perhaps the user okayed a preference dialog, and now
the main gui is re-opening with updated setting..
corz_GUIAnimateOpen($my_gui, "bottom", "test.ini", "my fx")
Examples of how to automate implementation of GUI fx in your code..
The long-winded versions of the animation strings are most useful; they
can be used directly in menus, which greatly simplifies the code
required to implement user-selectable window animations.
It's fairly easy to animate directly from either saved ini settings, or
user-selected preferences, or just save and retrieve settings, or both,
and keep both those things synchronized in the process.
Giving the user control is always a good thing (particularly when it's
in layers of expertise), and personally, I like my tools to attach to
specific areas of my desktop. The bonus of having these tools "slide
out" of a particular area of the desktop only adds to the user's feeling
of control.
So let's say we wanted to create a tray menu for the user to select an
animation style for your (their) program. The trick is, when we create
the menu items, we use the actual text of the animation strings.
Here's a complete tray menu you can rip right off the page..
TrayCreateItem("")
global $TrayMenuWinAnim = TrayCreateMenu("Window animation..")
; we could re-use this array to create other controls (see the included example scripts)..
local $win_anims[11] = ["Slide Left", "Slide Right", "Slide Top", "Slide Bottom", _
"Slide Top Left", "Slide Top Right", "Slide Bottom Right", "Slide Bottom Left", _
"Explode/Implode", "Fade", "Disable window animation"]
global $menu_items_win_anim[11]
for $i = 0 to 10
$menu_items_win_anim[$i] = TrayCreateItem($win_anims[$i], $TrayMenuWinAnim, -1, 1)
TrayItemSetOnEvent(-1, "MenuSetWinAnim")
next
for $i in $menu_items_win_anim
if TrayItemGetText($i) = $my_fx then TrayItemSetState($i, $TRAY_CHECKED)
next
TrayCreateItem("")
We can then use this exact same text to set the animation fx in the
called function. Our fictional MenuSetWinAnim() function would be a
skinny thing that might look very much like this..
func MenuSetWinAnim()
corz_GUIAnimateOpen("", TrayItemGetText(@TRAY_ID), "test.ini", "my fx")
endfunc
Or, if you wanted to grab the animation codes array for later use (a
good idea, and while we're with the good ideas, you would of course be
using variables of some sort)..
func MenuSetWinAnim()
global $my_codes = corz_GUIAnimateOpen("", TrayItemGetText(@TRAY_ID), $ini_path, $section)
endfunc
Then, whenever you need to animate any window, you simply feed the codes
to the animate functions, like so..
corz_GUIAnimateOpen($my_gui, $my_codes)
Even if you didn't get the codes, or even know the animation string, you
could still perform the window's current animation, like so..
corz_GUIAnimateOpen($my_gui, EnvGet('gui_fx'))
All parameters are optional. You can retrieve settings, or save settings,
or perform a window animation, or any or all of those things at once.
Simply put; If you want an animation, include the gui handle. If you
don't want an animation, don't. If you want to save or retrieve
settings, include ini parameters. If you want to save settings, include
the animation string, and if you want to retrieve settings, don't.
See the included "corz_gui_fx [tray+combo example].au3" and "corz_gui_fx
[combo example].au3" for simple working demos of gui fx.
#ce
func corz_GUIAnimateOpen($some_gui="", $GUIFX="", $ini_file="", $ini_section="")
if not $some_gui then
return corz_GUIGetFX($GUIFX, $ini_file , $ini_section)
else
if not IsArray($GUIFX) then
$GUIFX = corz_ValidateFXCodes($GUIFX, $ini_file, $ini_section)
endif
switch $GUIFX[1]
case "-" ; animation has been disabled
GUISetState(@SW_SHOW, $some_gui)
return
case "fade" ; we won't use the dll call version of the fade, it's nasty.
corz_GUIFadeIn($some_gui)
case else
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $some_gui, "int", 200, "long", $GUIFX[1])
GUISetState(@SW_SHOW, $some_gui)
endswitch
return $GUIFX
endif
endfunc
; corz_GUIAnimateClose()
; Animate the closing of a window.
;
; Usage as corz_GUIAnimateOpen() (above)
;
; Note: At the end of this function, the window is in a HIDDEN state.
;
func corz_GUIAnimateClose($some_gui="", $GUIFX="", $ini_file="", $ini_section="")
; I'd love to slip this in somehow, to release the memory (at least, in appearance)
; but there's just no way to do it without flashing the window, afaik.
; GUISetState(@SW_MINIMIZE, $some_gui) ; I tried *everything* :/
if not $some_gui then
return corz_GUIGetFX($GUIFX, $ini_file, $ini_section)
else
if not IsArray($GUIFX) then
$GUIFX = corz_ValidateFXCodes($GUIFX, $ini_file, $ini_section)
endif
switch $GUIFX[1]
case "-"
GUISetState(@SW_HIDE, $some_gui)
return
case "fade"
GUISetState(@SW_SHOW, $some_gui)
corz_GUIFadeOut($some_gui)
case else
GUISetState(@SW_SHOW, $some_gui)
DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $some_gui, "int", 200, "long", $GUIFX[2])
GUISetState(@SW_HIDE, $some_gui)
endswitch
return $GUIFX
endif
endfunc
; fade-in..
;
; you can access these two directly, too.
func corz_GUIFadeIn($some_gui)
WinSetTrans($some_gui, "", 0)
GUISetState(@SW_SHOW, $some_gui)
for $i = 0 to 240 step 15
WinSetTrans($some_gui, "", $i)
Sleep(5)
next
WinSetTrans($some_gui, "", 255)
endfunc
; and out
; sadly, setting the transparency away from max causes the window to flicker briefly.
; but that's still better than the dll call version, which can basically disable the
; parent gui permanently.
func corz_GUIFadeOut($some_gui)
for $i = 240 to 15 step - 15
Sleep(5)
WinSetTrans($some_gui, "", $i)
next
GUISetState(@SW_HIDE, $some_gui)
endfunc
; This enables you to send everything directly to corz_GUIAnimateOpen/Close()
;
;
; if we are already working with the animation codes, go away quickly, get on
; with the animaton. if we need to create valid codes, or it's a simple disable
; or fade, invoke corz_GUIGetFX().
func corz_ValidateFXCodes(ByRef $GUIFX, $ini_file="", $ini_section="")
if IsArray($GUIFX) then return
$GUIFX = corz_GUIGetFX($GUIFX, $ini_file, $ini_section)
return $GUIFX
endfunc
#cs
corz_GUIGetFX( [string{fx setting} [, string{path to ini file} [, string{ini section} [, string{ini key}]]]])
All parameters are optional.
This function validates the supplied animation string (retrieving it from
the ini if no code/string is supplied), and returns an array of valid
animation codes for later use, possibly by corz_GUIAnimateOpen/Close()
If the supplied string is invalid, corz_GUIGetFX() makes it valid. Finally,
if valid ini parameters were specified, the new animation string is saved to
the ini file..
Feed it the path and section name of the ini file you would like to use to
(re)store the settings, and your chosen setting (or omit that, if you want
corz_GUIGetFX() to grab it from the ini file, or create it anew, if no
ini setting exists). See corz_GUIAnimateOpen(above) for a list of the
available animation strings.
As with corz_GUIAnimateOpen(), the long-winded versions can be used directly
in menus..
$menu_item[2] = TrayCreateItem("Slide Right", $TrayMenuWinAnim, -1, 1)
TrayItemSetOnEvent(-1, "MenuSetWinAnim")
Inside our fictional MenuSetWinAnim() function we would need to do no more
than..
$my_codes = corz_GUIGetFX(TrayItemGetText(@TRAY_ID), $ini_path, $section)
This does ezactly the same thing, but *slightly* slower..
$my_codes = corz_GUIAnimateOpen("", TrayItemGetText(@TRAY_ID), $ini_path, $section)
Either way, if the user selects the item with the text "Slide right" (or
whatever), corz_GUIGetFX() returns the valid animation codes into
$my_codes (now an array) for later use. Then, when you need to animate any
window, you simply feed this to the animate functions, like so..
corz_GUIAnimateOpen($my_gui, $my_codes)
and corz_GUIAnimateOpen() will choose the correct code ($my_codes[1]) and
perform the required animation. $my_codes can hang around your application
for whenever you need to animate a window (i.e. make it global).
Of course, you can also call the open and close functions to perform these
operations, but I figured you may want to access them directly, too.
Whichever way you go, to you, the coder, and to the user, it's just a bunch
of cute strings.
Usage:
The simplest form of usage is..
$my_var = corz_GUIGetFX()
Which will return an array of animation codes for "Slide Right" (the default
animation). If you want to specify the animation, but don't need to (re)store
any settings, use..
$my_var = corz_GUIGetFX("bottom") ; or whatever
If you want to specify an ini file for the settings, but leave everything
else to corz_GUIGetFX(), use..
$my_var = corz_GUIGetFX("", "C:\ini.file", "section name")
and corz_GUIGetFX() will retrieve the last saved settings and apply them.
If no settings were found, it creates them. At the end, it saves them.
If you are trigerring all this from menus (as in above example), or similar,
there's no need to do anything else, corz_GUIGetFX() will keep the ini
file constantly updated with the latest settings.
Another reason why you might want to interact directly with
corz_GUIGetFX() is to override the name of the ini key/environment variable.
Usually it is "gui_fx", but you might be animating lots of windows within a
single application, each with individual settings.
Then you could access the simple animation string of any window by getting
the environment variable with its name; i.e..
GUICtrlSetData($combo_img_tools, EnvGet('image_tools'))
or whatever. And although you could also do this..
corz_GUIAnimateOpen($gui_img_tools, EnvGet('image_tools'))
you would most likely be working with the codes directly, having grabbed
them already.
#ce
func corz_GUIGetFX($fx="", $fx_ini_path="", $fx_ini_section="corz gui fx", $fx_win = "gui_fx")
if $fx_ini_path and $fx = "" then
$fx = IniRead($fx_ini_path, $fx_ini_section, $fx_win, "Slide right")
endif
switch $fx
case "-", "Disabled", "disable", "Disable window animation"
local $GUIFX[3] = [2, "disable", "disable"] ; it don't like "-" here :/
case "fade"
local $GUIFX[3] = [2, "fade", "fade"]
case "Slide Left", "Left", "Slide L", "l"
local $GUIFX[3] = [2, '0x00040001', '0x00050002'] ; hex looks better darker (in my color scheme ;o)
case "Slide Top", "Slide T", "Top", "t"
local $GUIFX[3] = [2, '0x00040004', '0x00050008']
case "Slide Right", "Right", "Slide R", "Slide", "r"
local $GUIFX[3] = [2, '0x00040002', '0x00050001']
case "Slide Bottom", "Slide B", "Bottom", "b"
local $GUIFX[3] = [2, '0x00040008', '0x00050004']
case "Slide Top Left", "Top Left", "top-left", "tl", "diagonal tl", "d"
local $GUIFX[3] = [2, '0x00040005', '0x0005000a']
case "Slide Top Right", "Top Right", "top-right", "tr", "diagonal tr"
local $GUIFX[3] = [2, '0x00040006', '0x00050009']
case "Slide Bottom Right", "Bottom Right", "bottom-right", "br", "diagonal br"
local $GUIFX[3] = [2, '0x0004000a', '0x00050005']
case "Slide Bottom Left", "Bottom Left", "bottom-left", "bl", "diagonal bl"
local $GUIFX[3] = [2, '0x00040009', '0x00050006']
case "x", "Implode/Explode", "Explode/Implode", "Explode", "Implode"
local $GUIFX[3] = [2, '0x00040010', '0x00050010']
case "" ; deleted in the ini!
continuecase
case else
$fx = "Slide Right"
local $GUIFX[3] = [2, '0x00040002', '0x00050001']
endswitch
EnvSet($fx_win, $fx)
if $fx_ini_path then IniWrite($fx_ini_path, $fx_ini_section, $fx_win, $fx)
return $GUIFX
endfunc