au3 0.1.1 → 0.1.2

data/lib/AutoItX3/process.rb

@@ -1,6 +1,6 @@
 #Encoding: UTF-8
 #This file is part of au3. 
-#Copyright © 2009 Marvin Gülker
+#Copyright © 2009, 2010 Marvin Gülker, Steven Heidel
 #
 #au3 is published under the same terms as Ruby. 
 #See http://www.ruby-lang.org/en/LICENSE.txt
@@ -36,7 +36,18 @@ module AutoItX3
     #call-seq: 
     #  close_process(pid) ==> nil
     #  kill_process(pid) ==> nil
+    #
     #Closes the given process. 
+    #===Parameters
+    #[+pid+] The PID or name of the process to close. 
+    #===Return value
+    #nil. 
+    #===Example
+    #  AutoItX3.close_process(1234)
+    #===Remarks
+    #This method doesn't ask the process to terminate nicely, it just kills it. 
+    #If you're familiar with Unix process signals, this method is nearer to 
+    #sending SIGKILL than sending SIGTERM. 
     def close_process(pid)
       @functions[__method__] ||= AU3_Function.new("ProcessClose", 'S', 'L')
       @functions[__method__].call(pid.to_s.wide)
@@ -44,20 +55,35 @@ module AutoItX3
     end
     alias kill_process close_process
     
-    #Checks wheather or not the given name or PID exists. If successful, 
-    #this method returns the PID of the process. 
+    #Checks wheather or not the given name or PID exists. 
+    #===Parameters
+    #[+pid+] The PID or name of the process to check. 
+    #===Return value
+    #false if the process doesn't exist, otherwise the PID of the process. 
+    #===Example
+    #  p AutoItX3.process_exists?(1234) #=> false
+    #  p AutoItX3.process_exists("ruby.exe") #=> 4084
     def process_exists?(pid)
       @functions[__method__] ||= AU3_Function.new("ProcessExists", 'S', 'L')
       pid = @functions[__method__].call(pid.to_s.wide)
-      if pid == 0
-        false
-      else
-        pid
-      end
-      
+      pid > 0 && pid
     end
     
-    #Sets a process's priority. Use one of the *_PRIORITY constants. 
+    #Sets a process's priority. 
+    #===Parameters
+    #[+pid+] The PID or name of the process whose priority you want to change. 
+    #[+priority+] One of the *_PRIORITY constants. 
+    #===Return value
+    #The argument passed as +priority+. 
+    #===Raises
+    #[Au3Error] You passed an invalid priority value or some other error occured. 
+    #===Example
+    #  AutoItX3.set_process_priority(4084, AutoItX3::HIGH_PRIORITY)
+    #  AutoItX3.set_process_priority("ruby.exe", AutoItX3::SUBNORMAL_PRIORITY)
+    #===Remarks
+    #You shouldn't set a process's priority to REALTIME_PRIORITY, since that 
+    #is the priority system processes run with which are likely more important than your process. 
+    #The same goes the other way round: Don't decrease a system process's priority. 
     def set_process_priority(pid, priority)
       @functions[__method__] ||= AU3_Function.new("ProcessSetPriority", 'SL', 'L')
       @functions[__method__].call(pid.to_s.wide, priority)
@@ -70,37 +96,54 @@ module AutoItX3
       end
     end
     
-    #Waits for the given process name to exist. This is the only process-related 
-    #method that doesn't take a PID, because to wait for a special PID doesn't make 
-    #sense, since PIDs are generated randomly. 
-    #
-    #Return false if +timeout+ was reached. 
+    #Waits for the given process name to exist. 
+    #===Parameters
+    #[+procname+] The name of the process to wait for. 
+    #[+timeout+] (+0+)  The time to wait, in seconds. The default is to wait infinitely. 
+    #===Return value
+    #true if the process was found, false if +timeout+ was reached. 
+    #===Example
+    #  AutoItX3.wait_for_process("nonexistant.exe", 2) #| false
+    #  AutoItX3.wait_for_process("ruby.exe") #| true
+    #===Remarks
+    #This is the only process-related method that doesn't take a PID, 
+    #because to wait for a special PID doesn't make sense, since PIDs 
+    #are generated randomly. 
     def wait_for_process(procname, timeout = 0)
       @functions[__method__] ||= AU3_Function.new("ProcessWait", 'SL', 'L')
-      if @functions[__method__].call(procname.to_s.wide, timeout) == 0
-        false
-      else
-        true
-      end
+      @functions[__method__].call(procname.to_s.wide, timeout) == 1
     end
     
     #Waits for the given process name or PID to disappear. 
-    #
-    #Returns false if +timeout+ was reached. 
+    #===Parameters
+    #[+pid+] The PID or process name to wait for. 
+    #[+timeout+] The time to wait, in seconds. 0 means to wait infinitely, which is the default. 
+    #===Return value
+    #true if the process disappeared, false if +timeout+ was reached. 
+    #===Example
+    #  AutoItX3.wait_for_process_close(4084) #| true
+    #  AutoItX3.wait_for_process_close("ruby.exe", 1) #| false
+    #  #Attention on this one: 
+    #  AutoItX3.wait_for_process_close("nonexistant.exe") #| true
     def wait_for_process_close(pid, timeout = 0)
       @functions[__method__] ||= AU3_Function.new("ProcessWaitClose", 'SL', 'L')
-      if @functions[__method__].call(pid.to_s.wide, timeout) == 0
-        false
-      else
-        true
-      end
+      @functions[__method__].call(pid.to_s.wide, timeout) == 1
     end
     
-    #Runs a program. The program flow continues, if you want to wait for the process to 
+    #Runs a program. 
+    #===Parameters
+    #[+name+] The command to run. 
+    #[+workingdir+] (<tt>""</tt>) The working directory to start the process in. Default is the current one. 
+    #[+flag+] (+1+) Additional properties you want to set on the window. Possible value include SW_HIDE, SW_MINIMIZE and SW_MAXIMIZE, which are defined as constants of the Window class. Default is to set nothing. 
+    #===Return value
+    #The PID of the newly created process. 
+    #===Raises
+    #[Au3Error] Couldn't awake the specified program. 
+    #===Example
+    #  p AutoItX3.run("notepad.exe") #=> 502
+    #===Remarks
+    #The program flow continues; if you want to wait for the process to 
     #finish, use #run_and_wait. 
-    #Returns the PID of the created process or nil if there was a failure starting the process. 
-    #The +flag+ parameter can be one of the SW_HIDE, SW_MINIMZE or SW_MAXIMIZE 
-    #constants in the Window class. 
     def run(name, workingdir = "", flag = 1)
       @functions[__method__] ||= AU3_Function.new("Run", 'SSL', 'L')
       pid = @functions[__method__].call(name.wide, workingdir.wide, flag)
@@ -108,11 +151,23 @@ module AutoItX3
       pid
     end
     
-    #Runs a program. This method waits until the process has finished and returns 
-    #the exitcode of the process (or false if there was an error initializing it). If 
-    #you don't want this behaviour, use #run. 
-    #The +flag+ parameter can be one of the SW_HIDE, SW_MINIMZE or SW_MAXIMIZE 
-    #constants in the Window class. 
+    #Runs a program and waits until the process has finished. 
+    #===Parameters
+    #[+name+] The command to run. 
+    #[+workingdir+] (<tt>""</tt>) The working directory to start the process in. Default is the current one. 
+    #[+flag+] (+1+) Additional properties you want to set on the window. Possible value include SW_HIDE, SW_MINIMIZE and SW_MAXIMIZE, which are defined as constants of the Window class. Default is to set nothing. 
+    #===Return value
+    #The exitcode of the process. 
+    #===Raises
+    #[Au3Error] Couldn't awake the specified program. 
+    #===Example
+    #  AutoItX3.run_and_wait("ipconfig") #| 0
+    #  AutoItX3.run_and_wait("nonexistant.exe")
+    #===Remarks
+    #If you don't want to wait until the program has finished, use #run. 
+    #
+    #This method doesn't do anything different from Ruby's own Kernel#system method beside 
+    #the flag you can pass to GUI applications. 
     def run_and_wait(name, workingdir = "", flag = 1)
       @functions[__method__] ||= AU3_Function.new("RunWait", 'SSL', 'L')
       exitcode = @functions[__method__].call(name.wide, workingdir.wide, flag)
@@ -121,7 +176,19 @@ module AutoItX3
     end
     
     #Changes the the owner of following  #run and #run_and_wait methods to the given 
-    #user. Raises a NotImplementedError if your system is Win2000 or older. 
+    #user. 
+    #===Parameters
+    #[+username+] The name of the user you want to run commands as. 
+    #[+domain+] The user's domain. 
+    #[+password+] The user's password. 
+    #[+options+] (+1+) One of the following: 0: don't load the user profile, 1 (default): load the user profile, 2: Only for networking. 
+    #===Return value
+    #nil. 
+    #===Raises
+    #[NotImplementedError] You're using Windows ME or earlier which don't support this method. 
+    #===Example
+    #  AutoItX3.run_as_set("Rubyist", "WORKGROUP", "MyFamousUncrackablePassword")
+    #  AutoItX3.run("hack_them_all.exe")
     def run_as_set(username, domain, password, options = 1)
       @functions[__method__] ||= AU3_Function.new("RunAsSet", 'SSSI', 'L')
       if @functions[__method__].call(username.wide, domain.wide, password.wide, options) == 0
@@ -130,23 +197,21 @@ module AutoItX3
       nil
     end
     
-    #Executes one of the the following commands: 
-    #- SHUTDOWN
-    #- REBOOT
-    #- LOGOFF
-    #You can combine the above actions with the below constants, except 
-    #LOGOFF and POWER_DOWN. Use the + operator to combine them. 
-    #- FORCE_CLOSE
-    #- POWER_DOWN
+    #Shuts down or reboots your computer, or logs you off. 
+    #===Parameters
+    #[+code+] One of the following constants: SHUTDOWN, REBOOT, LOGOFF. You may combine (by using addition with +) each of them with FORCE_CLOSE which forces all hanging applications to close. Additionally, you may combine SHUTDOWN with POWEROFF which ensures that your computer gets cut off from the power supply.     
+    #===Return value
+    #Unknown. 
+    #===Example
+    #  AutoItX3.shutdown(AutoItX3::LOGOFF | AutoItX3::FORCE_CLOSE)
+    #  AutoItX3.shutdown(AutoItX3::REBOOT)
+    #  AutoItX3.shutdown(AutoItX3::SHUTDOWN + AutoItX3::FORCE_CLOSE + AutoItX3::POWEROFF)
+    #  #If your computer is still running after executing this sequence of commands, you may should check your hardware. 
     def shutdown(code)
       @functions[__method__] ||= AU3_Function.new("Shutdown", 'L', 'L')
-      if @functions[__method__].call(code) == 0
-        false
-      else
-        true
-      end
+      @functions[__method__].call(code) == 1
     end
     
   end
   
-end
+end

data/lib/AutoItX3/window.rb

@@ -1,6 +1,6 @@
 #Encoding: UTF-8
 #This file is part of au3. 
-#Copyright © 2009 Marvin Gülker
+#Copyright © 2009, 2010 Marvin Gülker, Steven Heidel
 #
 #au3 is published under the same terms as Ruby. 
 #See http://www.ruby-lang.org/en/LICENSE.txt
@@ -12,6 +12,19 @@ module AutoItX3
   #If you want to get a real handle to the window, 
   #call #handle on your Window object (but you won't 
   #need that unless you want to use it for Win32 API calls). 
+  #
+  #Every window is clearly defined by two properties: The window't title 
+  #(or at least a part of it, see AutoItX3.opts) and it's text. 
+  #In most cases you can ignore the text, since a window's title is usually 
+  #enough to identify a window, but if you're only using parts of titles, you may have 
+  #to check texts as well, but be prepared that the "text" a window holds 
+  #doesn't have to correspond with the text you actually see on the window. 
+  #If you set a method's +text+ parameter to an empty string (which is the default), 
+  #a window will only be searched for by title. 
+  #
+  #Please also note that the handle a Window object holds gets invalid if the window it 
+  #refers to is closed. This class doesn't automatically notify you if that occures, so 
+  #don't wonder about "window not found" errors after a window was closed. 
   class Window
     
     #A window describing the desktop. 
@@ -48,18 +61,28 @@ module AutoItX3
       end
       
       #Checks if a window with the given properties exists. 
+      #===Parameters
+      #[+title+] The window's title. 
+      #[+text+] (<tt>""</tt>) The window's text. 
+      #===Return value
+      #true or false. 
+      #===Example
+      #  p AutoItX3::Window.exists?("Untitled - notepad") #=> true
+      #  p AutoItX3::Window.exists?("Nonexistant") #=> false
       def exists?(title, text = "")
         @functions[__method__] ||= AU3_Function.new("WinExists", 'SS', 'L')
-        if @functions[__method__].call(title.wide, text.wide) == 0
-          return false;
-        else
-          return true;
-        end
+        @functions[__method__].call(title.wide, text.wide) == 1
       end
       
-      #Returns a two-element array of form <tt>[x , y]</tt> reflecting the 
-      #position of the caret in the active window. This doesn't work with 
-      #every window. 
+      #Returns the position of the caret in the active window. 
+      #===Return value
+      #A two-element array of form <tt>[x , y]</tt>, which are meant to be row and column, not pixel values. 
+      #===Example
+      #  p AutoItX3::Window.caret_pos #=> [8, 28]
+      #===Remarks
+      #This doesn't work with every window. Many MDI windows, for example, use absolute coordinates and yet other always report static coordinates. 
+      #
+      #The caret is the blinking pipe cursor that is displayed when editing lines of text (it has nothing to do with the mouse cursor). 
       def caret_pos
         @functions[:caret_pos_x] ||= AU3_Function.new("WinGetCaretPosX", '', 'L')
         @functions[:caret_pos_y] ||= AU3_Function.new("WinGetCaretPosY", '', 'L')
@@ -69,6 +92,10 @@ module AutoItX3
       end
       
       #Minimizes all available windows. 
+      #===Return value
+      #nil. 
+      #===Example
+      #  AutoItX3::Window.minimize_all
       def minimize_all
         @functions[__method__] ||= AU3_Function.new("WinMinimizeAll", '')
         @functions[__method__].call
@@ -76,15 +103,28 @@ module AutoItX3
       end
       
       #Undoes a previous call to Window.minimize_all. 
+      #===Return value
+      #nil. 
+      #===Example
+      #  AutoItX3::Window.minimize_all
+      #  sleep 3
+      #  AutoItX3::Window.undo_minimize_all
       def undo_minimize_all
         @functions[__method__] ||= AU3_Function.new("WinMinimizeAllUndo", '')
         @functions[__method__].call
         nil
       end
       
-      #Waits for a window with the given properties to exist. You may 
-      #specify a +timeout+ in seconds. +wait+ normally returns true, but if 
-      #the timeout is expired, it returns false. 
+      #Waits for a window with the given properties to exist. 
+      #===Parameters
+      #[+title+] The title of the window to wait for. 
+      #[+text+] (<tt>""</tt> The text of the window to wait for. 
+      #[+timeout+] (+0+) The time to wait for, in seconds. Zero means to wait infinitely. 
+      #===Return value
+      #true if the window has been found, false if +timeout+ was reached. 
+      #===Example
+      #  AutoItX3::Window.wait("Untitled - Notepad") #| true
+      #  AutoItX3::Window.wait("Nonexistant", 3) #| false
       def wait(title, text = "", timeout = 0)
         @functions[__method__] ||= AU3_Function.new("WinWait", 'SSL', 'L')
         @functions[__method__].call(title.wide, text.wide, timeout) != 0
@@ -92,11 +132,16 @@ module AutoItX3
       
     end
     
-    #Creates a new Window object. This method checks if a window 
-    #with the given properties exists (via Window.exists?) and raises 
-    #an Au3Error if it does not. Use Window::DESKTOP_WINDOW as 
-    #the +title+ to get a window describing the desktop. Use Window::ACTIVE_WINDOW 
-    #as the +title+ to get a window describing the active (foreground) window. 
+    #Creates a new Window object. 
+    #===Parameters
+    #[+title+] The title of the window you want a reference to. Use DESKTOP_WINDOW for a handle to the desktop and ACTIVE_WINDOW for a handle to the currently selected window. 
+    #[+text+] The text of the window you want a reference to. 
+    #===Return value
+    #The newly created Window object. 
+    #===Raises
+    #[Au3Error] No window with the given properties was found. 
+    #===Example
+    #  win = AutoItX3::Window.new("Untitled - Notepad")
     def initialize(title, text = "")
       @title = title
       @text = text
@@ -105,22 +150,35 @@ module AutoItX3
     
     #Human-readable output of form <tt>"<Window: WINDOW_TITLE (WINDOW_HANDLE)>"</tt>. 
     #The title is determined by calling #title. 
-    def inspect
+    def inspect # :nodoc:
       "<Window: #{title} (#{handle})>"
     end
     
-    #Returns +self+'s title by returning the value of @title. 
+    #Returns the window's title. 
+    #===Return value
+    #+self+'s title by (the value of <tt>@title</tt>). 
+    #===Example
+    #  puts win.to_s #=> Untitled - Notepad
     def to_s
       @title
     end
     
-    #Returns the handle of the window as an integer by calling 
-    #<tt>.to_i(16)</tt> on the result of #handle. 
+    #Returns the actual handle of the window. 
+    #===Return value
+    #The window's handle as an integer. 
+    #===Example
+    #  p win.handle #=> 721996
+    #===Remarks
+    #See also #handle. 
     def to_i
       handle.to_i(16)
     end
     
     #Activates the window and returns true if it was successfully activated (using #active? to check). 
+    #===Return value
+    #true if the window is activated now, otherwise false. 
+    #===Example
+    #  win.activate
     def activate
       Window.functions[__method__] ||= AU3_Function.new("WinActivate", 'SS')
       Window.functions[__method__].call(@title.wide, @text.wide)
@@ -128,16 +186,24 @@ module AutoItX3
     end
     
     #Checks wheather or not the window is active. 
+    #===Return value
+    #true if the window is active, otherwise false. 
+    #===Example
+    #  p win.active? #=> false
+    #  win.activate #| true
+    #  p win.active? #=> true
     def active?
       Window.functions[__method__] ||= AU3_Function.new("WinActive", 'SS', 'L')
-      if Window.functions[__method__].call(@title.wide, @text.wide) == 0
-        return false
-      else
-        return true
-      end
+      Window.functions[__method__].call(@title.wide, @text.wide) == 1
     end
     
-    #Sends WM_CLOSE to +self+. WM_CLOSE may be processed by the window, 
+    #Sends WM_CLOSE to +self+. This is like clicking on the [X] button on top of the window. 
+    #===Return value
+    #nil. 
+    #===Example
+    #  win.close
+    #===Remarks
+    #WM_CLOSE may be processed by the window, 
     #it could, for example, ask to save or the like. If you want to kill a window 
     #without giving the ability to process your message, use the #kill method. 
     def close
@@ -151,12 +217,25 @@ module AutoItX3
     #  valid? ==> true or false
     #
     #Calls the Window.exists? class method with the values given in Window.new. 
+    #===Return value
+    #true if this object refers to an existing window, false otherwise. 
+    #===Example
+    #  p win.exists? #=> true
+    #  win.close
+    #  p win.exists? #=> false
     def exists?
       Window.exists?(@title, @text)
     end
     alias valid? exists?
     
-    #*Returns an array of all used window classes of +self+. 
+    #Returns an array of all used window classes of +self+. 
+    #===Return value
+    #An array containg all the window classes as strings. 
+    #===Raises
+    #[Au3Error] Window not found. 
+    #===Example
+    #  p win.class_list 
+    #  #=> ["SciTEWindowContent", "Scintilla", "Scintilla", "ToolbarWindow32", "SciTeTabCtrl", "msctls_statusbar32"]
     def class_list
       Window.functions[__method__] ||= AU3_Function.new("WinGetClassList", 'SSPI')
       buffer = " " * AutoItX3::BUFFER_SIZE
@@ -166,20 +245,34 @@ module AutoItX3
       buffer.normal.split("\n").map{|str| str.strip.empty? ? nil : str.strip}.compact
     end
     
-    #Returns the client area size of +self+ as a two-element array of 
-    #form <tt>[ width , height ]</tt>. Returns <tt>[0, 0]</tt> on minimized 
+    #Gets the size of a window's client area. 
+    #===Return value
+    #A two-element array of form <tt>[ width , height ]</tt>. Returns <tt>[0, 0]</tt> on minimized 
     #windows. 
+    #===Raises
+    #[Au3Error] Window not found. 
+    #===Example
+    #  p win.client_size #=> [784, 564]
+    #  #Minimized: 
+    #  p win.client_size #=> [0, 0]
     def client_size
       Window.functions[:client_size_width] ||= AU3_Function.new("WinGetClientSizeWidth", 'SS', 'L')
       Window.functions[:client_size_height] ||= AU3_Function.new("WinGetClientSizeHeight", 'SS', 'L')
-      size = [Window.functions[:client_size_width].call, Window.functions[:client_size_height].call]
+      size = [Window.functions[:client_size_width].call(@title.wide, @text.wide), Window.functions[:client_size_height].call(@title.wide, @text.wide)]
       raise_unfound if AutoItX3.last_error == 1
       size
     end
     
-    #Returns the numeric handle of a window as a string. It can be used 
-    #with the WinTitleMatchMode option set to advanced or for direct calls 
-    #to the windows API (but you have to call <tt>.to_i(16)</tt> on the string then). 
+    #Returns the handle of a window. 
+    #===Return value
+    #Returns the numeric handle of a window as a string. 
+    #===Raises
+    #[Au3Error] Window not found. 
+    #===Example
+    #  p win.handle #=> "00070388"
+    #===Remarks
+    #You may use the handle for instead of passing a title to Window.new or directly for 
+    #Win32API calls (make sure you call <tt>.to_i(16)</tt> on the string before).  
     def handle
       Window.functions[__method__] ||= AU3_Function.new("WinGetHandle", 'SSPI')
       buffer = " " * AutoItX3::BUFFER_SIZE
@@ -189,8 +282,18 @@ module AutoItX3
       buffer.normal.strip
     end
     
+    #Gets a window's rectangle. 
+    #===Return value
     #Returns the position and size of +self+ in a four-element array 
-    #of form <tt>[x, y, width, height]</tt>. 
+    #of form <tt>[x, y, width, height]</tt>. If called on a minimized window, 
+    #the X and Y values are nonsense, but +width+ and +height+ indicate the 
+    #size of the window's bar in the taskbar. 
+    #===Raises
+    #[Au3Error] Window not found. 
+    #===Example
+    #  p win.rect #=> [240, 191, 800, 600]
+    #  #Called on a minimized window: 
+    #  p win.rect #=> [4294935296, 4294935296, 160, 25]
     def rect
       Window.functions[:xpos] ||= AU3_Function.new("WinGetPosX", 'SS', 'L')
       Window.functions[:ypos] ||= AU3_Function.new("WinGetPosY", 'SS', 'L')
@@ -210,8 +313,14 @@ module AutoItX3
       rect
     end
     
+    #Gets the PID of the process running a window. 
+    #===Return value
     #Returns the process identification number of +self+'s window 
     #procedure. 
+    #===Raises
+    #[Au3Error] Window not found. 
+    #===Example
+    #  p win.pid #=> 3128
     def pid
       Window.functions[__method__] ||= AU3_Function.new("WinGetProcess", 'SSPI', 'L')
       buffer = " " * AutoItX3::BUFFER_SIZE
@@ -226,7 +335,10 @@ module AutoItX3
       end
     end
     
-    #Returns the integer composition of the states 
+    #Checks a window's state. You shouldn't use this function, use #exists?, 
+    ##visible?, #enabled?, #active?, #minimized? and #maximized? instead. 
+    #===Return value
+    #Returns the integer composition of the states: 
     #- exists (1)
     #- visible (2)
     #- enabled (4)
@@ -234,8 +346,12 @@ module AutoItX3
     #- minimized (16)
     #- maximized (32)
     #Use the bit-wise AND operator & to check for a specific state. 
-    #Or just use one of the predefined methods #exists?, #visible?, 
-    ##enabled?, #active?, #minimized? and #maximized?. 
+    #===Raises
+    #[Au3Error] Window not found. 
+    #===Example
+    #  #Check for visibility
+    #  p(win.state & 2) #=> 2 #visible
+    #  p(win.state & 2) #=> 0 #invisible
     def state
       Window.functions[__method__] ||= AU3_Function.new("WinGetState", 'SS', 'L')
       state = Window.functions[__method__].call(@title.wide, @text.wide)
@@ -243,28 +359,59 @@ module AutoItX3
       state
     end
     
-    #Returns true if +self+ is shown on the screen. 
+    #Checks wheather a window is visible or not. 
+    #===Return value
+    #Returns true if +self+ is shown on the screen, false otherwise. 
+    #===Raises
+    #[Au3Error] Window not found. 
+    #===Example
+    #  p win.visible? #=> true
     def visible?
       (state & 2) == 2
     end
     
-    #Returns true if +self+ is enabled (i.e. it can receive input). 
+    #Checks wheather a window can receive user input or not. 
+    #===Return value
+    #Returns true if +self+ is enabled, false otherwise. 
+    #===Raises
+    #[Au3Error] Window not found. 
+    #===Example
+    #  p win.enabled? #=> false
     def enabled?
       (state & 4) == 4
     end
     
-    #Returns true if +self+ is minimized to the taskbar. 
+    #Checks wheather or not a window is minimized to the taskbar. 
+    #===Return value
+    #Returns true if +self+ is minimized to the taskbar, false otherwise. 
+    #===Raises
+    #[Au3Error] Window not found. 
+    #===Example
+    #  p win.minimized? #=> true
     def minimized?
       (state & 16) == 16
     end
     
+    #Checks wheather or not this is a fullscreen window. 
+    #===Return value
     #Returns true if +self+ is maximized to full screen size. 
+    #===Raises
+    #[Au3Error] Window not found. 
+    #===Example
+    #  p win.maximized? #=> false
     def maximized?
       (state & 32) == 32
     end
     
     #Returns the text read from a window. This method doesn't query the @text instance 
     #variable, rather it calls the AU3_WinGetText function. 
+    #===Return value
+    #The window's text. It doesn't necassary make sense. 
+    #===Example
+    #  #Used on an explorer window: 
+    #  p win.text #=> "Navigationsleiste\nAdresse: C:\\Users\\marvin_g\\Desktop\\Automations\\au3\\trunk\\lib\nlib\nHostwrapper f├╝r gemeinsame Orte\nShellView\nFolderView\nMen├╝leiste"
+    #  #Some windows just don't have any text. 
+    #  p win.text #=> ""
     def text
       Window.functions[__method__] ||= AU3_Function.new("WinGetText", 'SSPI')
       buffer = " " * AutoItX3::BUFFER_SIZE
@@ -277,6 +424,10 @@ module AutoItX3
     #affect or even use the value of @title, that means you can use 
     #+title+ to retrieve titles from a window if you're working with the 
     #advanced window mode. 
+    #===Return value
+    #The window's title. 
+    #===Example
+    #  p win.title #=> "AutoItX Help"
     def title
       Window.functions[__method__] ||= AU3_Function.new("WinGetTitle", 'SSPI')
       buffer = " " * AutoItX3::BUFFER_SIZE
@@ -287,26 +438,64 @@ module AutoItX3
     
     #Kills +self+. This method forces a window to close if it doesn't close 
     #quickly enough (in contrary to #close which waits for user actions 
-    #if neccessary). Some windows cannot be +kill+ed (notably 
-    #Windows Explorer windows). 
+    #if neccessary). 
+    #===Return value
+    #nil. 
+    #===Example
+    #  win.kill
+    #  p win.exists? #=> false
+    #===Remarks
+    #Some windows cannot be +kill+ed (notably Windows Explorer windows). 
     def kill
       Window.functions[__method__] ||= AU3_Function.new("WinKill", 'SS', 'L')
       Window.functions[__method__].call(@title.wide, @text.wide)
       nil
     end
     
-    #Clicks the specified item in the specified menu. You may specify up to seven 
-    #submenus. 
+    #Clicks a menu entry. 
+    #===Parameters
+    #[+menu+] The name of the top menu, such as <tt>"File"</tt> (or rather <tt>"&File"</tt>; you have to prefix underlined letters with an ampersand sign &). 
+    #[<tt>*items</tt>] Up to 7 submenus, use this in the same matter as +menu+. 
+    #===Return value
+    #nil. 
+    #===Raises
+    #[Au3Error] Window not found. 
+    #===Example
+    #  #Open the "Help" entry in SciTE's "Help" menu: 
+    #  win.select_menu_item("&Help", "&Help")
+    #===Remarks
+    #You can't open a menu with this method, the last submenu has to be associated with an action like opening a dialog window. 
+    #
+    #If you experience troubles with entries containing three dots <tt>...</tt> you should check if those three dots aren't a 
+    #Unicode character like Horizontal Ellipsis (<tt>…</tt>, U+2026). Just try that character instead of three dots. 
     def select_menu_item(menu, *items)
-      Window.functons[__method__] ||= AU3_Function.new("WinMenuSelectItem", 'SSSSSSSSSS', 'L')
+      Window.functions[__method__] ||= AU3_Function.new("WinMenuSelectItem", 'SSSSSSSSSS', 'L')
       raise(ArgumentError, "Wrong number of arguments, maximum is seven items!") if items.size > 7 #(menu is the 8th)
+      items[6] = nil if items.size < 7
+      items.map!{|item| item.nil? ? "" : item}
       result = Window.functions[__method__].call(@title.wide, @text.wide, menu.wide, *items.map{|item| item.wide})
       raise_unfound if result == 0
       nil
     end
     
-    #Moves a window (and optionally resizes it). This does not work 
-    #with minimized windows. 
+    #Moves a window (and optionally resizes it). 
+    #===Parameters
+    #[+x+] The X coordinate to move the window to. 
+    #[+y+] The Y coordinate to move the window to. 
+    #[+width+] (<tt>-1</tt>) The window's new width. 
+    #[+height+] (<tt>-1</tt>) The window's new width. 
+    #===Return value
+    #nil. 
+    #===Example
+    #  #Move a window to (10|10): 
+    #  win.move(10, 10)
+    #  #Moves a windot to (100|100) and resizes it to 500 x 500: 
+    #  win.move(100, 100, 500, 500)
+    #  #Since you can't resize a window without moving it, use this to achieve 
+    #  #the same effect: 
+    #  win.move(win.rect[0], win.rect[1], 700, 700)
+    #===Remarks
+    #This does not work with minimized and maximized windows. 
     def move(x, y, width = -1, height = -1)
       Window.functions[__method__] ||= AU3_Function.new("WinMove", 'SSLLLL', 'L')
       Window.functions[__method__].call(@title.wide, @text.wide, x, y, width, height)
@@ -314,23 +503,67 @@ module AutoItX3
     end
     
     #Turn the TOPMOST flag of +self+ on or off. If activated, the window 
-    #will stay on top above all other windows.
+    #will stay on top above all other windows. 
+    #===Parameters
+    #[+val+] true or false. 
+    #===Return value
+    #The argument passed. 
+    #===Example
+    #  win.set_on_top = true
     def set_on_top=(val)
       Window.functions[__method__] ||= AU3_Function.new("WinSetOnTop", 'SSL', 'L')
       Window.functions[__method__].call(@title.wide, @text.wide, !!val)
       val
     end
     
-    #Sets +self+'s window state to one of the SW_* constants. 
+    #Sets +self+ to a specific state like "maximized". 
+    #===Parameters
+    #[+val+] The state the window should be set to. One of the SW_* constants of this class. 
+    #===Return value
+    #The argument passed. 
+    #===Example
+    #  #Mimize a window
+    #  win.state = AutoItX3::Window::SW_MINIMIZE
+    #  #Make it fullscreen
+    #  win.state = AutoItX3::Window::SW_MAXIMIZE
     def state=(val)
       Window.functions[__method__] ||= AU3_Function.new("WinSetState", 'SSL', 'L')
       Window.functions[__method__].call(@title.wide, @text.wide, val)
       val
     end
     
-    #Renames +self+. This does not change the internal @title 
-    #instance variable, so you can use this with the 
-    #advanced window mode. 
+    #Renames +self+. 
+    #===Parameters
+    #[+val+] The new title. 
+    #===Return value
+    #The argument passed. 
+    #===Example
+    #  win.title = "Use Ruby whenever you can"
+    #===Remarks
+    #This does not change the internal @title instance variable, so you can use this with the 
+    #advanced window mode; this has another issue, though. If you aren't working in advanced 
+    #window mode, you (pseudo) Ruby handle gets invalid, since it only references the window by title: 
+    #  irb(main):042:0> win.title = "xxx"
+    #  => "xxx"
+    #  irb(main):043:0> win
+    #  AutoItX3::Au3Error: Unable to find a window with title 'lib' and text ''!
+    #          from C:/Users/marvin_g/Desktop/Automations/au3/trunk/lib/AutoItX3/window
+    #  .rb:265:in `handle'
+    #          from C:/Users/marvin_g/Desktop/Automations/au3/trunk/lib/AutoItX3/window
+    #  .rb:154:in `inspect'
+    #  irb(main):044:0> win2 = AutoItX3::Window.new("xxx")
+    #  => <Window: xxx (00070388)>
+    #  irb(main):045:0> win2.title = "lib"
+    #  => "lib"
+    #  irb(main):046:0> win2
+    #  AutoItX3::Au3Error: Unable to find a window with title 'xxx' and text ''!
+    #          from C:/Users/marvin_g/Desktop/Automations/au3/trunk/lib/AutoItX3/window
+    #  .rb:265:in `handle'
+    #          from C:/Users/marvin_g/Desktop/Automations/au3/trunk/lib/AutoItX3/window
+    #  .rb:154:in `inspect'
+    #  irb(main):047:0> win
+    #  => <Window: lib (00070388)>
+    #  irb(main):048:0>
     def title=(val)
       Window.functions[__method__] ||= AU3_Function.new("WinSetTitle", 'SSS', 'L')
       Window.functions[__method__].call(@title.wide, @text.wide, val.wide)
@@ -341,8 +574,17 @@ module AutoItX3
     #  AutoItX3::Window#trans = val ==> val
     #  AutoItX3::Window#transparency = val ==> val
     #
-    #Sets the transparency of +self+ or raises a NotImplementedError 
-    #if the OS is Windows Millenium or older. 
+    #Sets a window's transparency. 
+    #===Parameters
+    #[+val+] The opacity you want the window set to; a numeric value between 0 (compelety transparent) and 255 (opaque). 
+    #===Return value
+    #The argument passed. 
+    #===Raises
+    #[NotImplementedError] You are using Windows Millenium or older which don't support transparent windows. 
+    #===Example
+    #  win.trans = 100
+    #===Remarks
+    #Note that a window whose transparency is set to 0 doesn't cause #visible? to return false. 
     def trans=(val)
       Window.functions[__method__] ||= AU3_Function.new("WinSetTrans", 'SSL', 'L')
       if Window.functions[__method__].call(@title.wide, @text.wide, val) == 0
@@ -352,31 +594,66 @@ module AutoItX3
     end
     alias transparency= trans=
     
-    #Waits for +self+ to exist. This method calls Window's class 
-    #method wait, so see Window.wait for more information. 
+    #Waits for +self+ to exist. 
+    #===Parameters
+    #[+timeout+] (+0+) The time to wait for the window to appear, in seconds. If set to 0 (which is the default), waits infinitely. 
+    #===Return value
+    #true if the window was found, false if +timeout+ was reached. 
+    #===Example
+    #  win.wait
+    #  #Only for 10 seconds
+    #  puts "Window doesn't exist" unless win.wait(10)
     def wait(timeout = 0)
       Window.wait(@title, @text, timeout)
     end
     
     #Waits for +self+ to be the active (that is, get the input focus). 
+    #===Parameters
+    #[+timeout+] (+0+) The time to wait, in seconds. 0 means waiting infinitely. 
+    #===Return value
+    #true if the window has been activated, false if +timeout+ was reached. 
+    #===Example
+    #  win.wait_active
+    #  #Only for 10 seconds
+    #  puts "YOU HAVE TO CLICK THE WINDOW!!!!!" unless win.wait_active(10)
     def wait_active(timeout = 0)
       Window.functions[__method__] ||= AU3_Function.new("WinWaitActive", 'SSL', 'L')
       Window.functions[__method__].call(@title.wide, @text.wide, timeout) != 0
     end
     
     #Waits for +self+ to be closed. 
+    #===Parameters
+    #[+timeout+] (+0+) The time to wait, in seconds. 0 means to wait till doomsday. 
+    #===Return value
+    #true if the window was closed, false if +timeout+ was reached. 
+    #===Example
+    #  win.wait_close(10) #Wait for 10 seconds
     def wait_close(timeout = 0)
       Window.functions[__method__] ||= AU3_Function.new("WinWaitClose", 'SSL', 'L')
       Window.functions[__method__].call(@title.wide, @text.wide, timeout) != 0
     end
     
     #Waits for +self+ to lose the input focus. 
+    #===Parameters
+    #[+timeout+] (+0+) The time to wait, in seconds. 0 means waiting infinitely. 
+    #===Return value
+    #true if the window has lost the input focus, false if +timeout+ was reached. 
+    #===Example
+    #  win.wait_not_active(10) #Wait for 10 seconds
     def wait_not_active(timeout = 0)
       Window.functions[__method__] ||= AU3_Function.new("WinWaitNotActive", 'SSL', 'L')
       Window.functions[__method__].call(@title.wide, @text.wide, timeout) != 0
     end
     
-    #Returns the actually focused control in +self+, a AutoItX3::Control object. 
+    #Gets the actually focused control in +self+. 
+    #===Return value
+    #A AutoItX3::Control object. 
+    #===Example
+    #  #For any control
+    #  c = win.focused_control
+    #  #If you're sure it's a textbox
+    #  t = AutoItX3::Edit.from_control(win.focused_control)
+    #===Remarks
     #Note that if the owning window doesn't have the input focus, you'll get an 
     #unusable Control object back. 
     def focused_control
@@ -387,9 +664,17 @@ module AutoItX3
       AutoItX3::Control.new(@title, @text, buffer.normal.strip)
     end
     
-    #Reads the text of the statusbar at position +part+. This method 
-    #raises an Au3Error if there's no statusbar, it's not a mscommon 
-    #statusbar or if you try to read a position out of range. 
+    #Reads the statusbar's text(s). 
+    #===Parameters
+    #[+part+] (+1+) The part of the statusbar to read, a 1-based index. 
+    #===Return value
+    #The text read. 
+    #===Raises
+    #[Au3Error] Couldn't read the statusbar's text. The window may doesn't have a statusbar, it's not a mscommon statusbar or you tried to read an index out of range. 
+    #===Example
+    #  p win.statusbar_text #=> "Loading..."
+    #===Remarks
+    #I couldn't get this method to work with whatever window I tried. Suggestions?
     def statusbar_text(part = 1)
       Window.functions[__method__] ||= AU3_Function.new("StatusbarGetText", 'SSLPI')
       buffer = " " * AutoItX3::BUFFER_SIZE