wet-winobj 0.1-mswin32

data/src/wet/winobjects/Window.rb

@@ -0,0 +1,537 @@
+=begin license
+Copyright (c) 2005, Qantom Software
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 
+Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 
+Neither the name of Qantom Software nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. 
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+(based on BSD Open Source License)
+=end
+require 'timeout'
+require 'wet/constants/testconstants.rb'
+require 'wet/winobjects/WinUtils.rb'
+require 'wet/utils/CompileUtils.rb'
+require 'wet/exceptions/RuntimeExceptions.rb'
+require 'wet/exceptions/CompileExceptions.rb'
+
+module Wet
+    module Winobjects
+=begin rdoc
+    Base class for all Win32 objects. All UI objects are considered
+    to be some sort of a window
+=end
+        class Window
+            
+            #Order _DOES_ matter. If you change the order in the following 
+            #array, bad things _WILL_ happen
+            @@WinClasses = [ "WinEdit", "WinLabel", "WinComboBox", \
+                 "WinCheckbox",  "WinRadio", "WinButton"]
+            
+            
+=begin rdoc
+        Constructor that accepts the window handle. Typically 
+        you dont have to directly instantiate this class. Window.create()
+        will instantiate the right type of window for you. 
+=end
+            def initialize(hwnd)
+                @hwnd = hwnd
+                if @hwnd != -1
+                    find_styles()
+                    # It would have been nice to do a lazy loading - find the 
+                    #children when required. But when the children() method
+                    # is called in quick succession, you hit the 'too many 
+                    # callbacks' problem. So do an early loading
+                    @children = find_children()                    
+                end
+
+            end
+            
+            
+=begin rdoc
+        Does this object represent a valid Win32 element that is being
+        displayed? Return true if yes, false otherwise
+=end
+            def exists?()
+                return @hwnd != -1
+            end
+            
+=begin rdoc
+        Given a window's hwnd, this class level method
+        creates an appropriate WinObject
+        
+        You usually dont have to call this method directly You 
+        should use one of the helper methods like 
+        Container(..).win_edit(...)
+=end 
+            def Window.create(hwnd)
+                
+                tmp_element = Window.new(hwnd) 
+                elem = nil
+                if hwnd != -1
+                    @@WinClasses.each do |wc|
+                        eval_string = "#{wc}::candidate_match?(tmp_element)"
+                        is_match = eval eval_string
+                        if is_match
+                            str_cls = "#{wc}.new(#{hwnd})"
+                            elem = eval str_cls
+                            break 
+                        end
+                    end
+                end
+                
+                if elem == nil
+                    elem = tmp_element
+                end
+                return elem
+            end            
+            
+=begin rdoc
+    Returns a string representing the element's text. The text property
+    has a different meaning depending on the type of the object. For,
+    for a parent window the text is the title; For a button, the text is the
+    value shown on the button, etc. 
+=end
+            def text()
+                assert_object_exists
+                return window_caption(@hwnd)             
+            end
+        
+=begin rdoc
+    Get the windows handle for this element
+=end
+            def hwnd()
+                return @hwnd
+            end
+       
+=begin rdoc
+    Get the string representing the win32 class name for this element
+=end    
+            def win_class()
+                assert_object_exists
+                return class_name(@hwnd) 
+            end
+            
+       
+=begin rdoc
+    Emulate a click on this element
+=end
+            def click()
+                assert_object_exists
+                return do_click(@hwnd) 
+            end
+       
+=begin rdoc
+        Find all the child_objects of this window. If the optional
+        reqd_class parameter is non-nil, then only the WinElements
+        that are of the type of 'reqd_class' are returned. 
+        
+        parameters = reqd_class (optional) - Should be an instance object
+        of the Class class
+        return An array of WinElements that match the 'reqd_class' 
+        criteria. If the reqd_class is nil, then all the children of this window
+        are returned. 
+=end
+            def child_objects(reqd_class = nil)
+                assert_object_exists
+                reqd_obj = []
+                if reqd_class == nil
+                    reqd_obj = @children
+                else
+                    @children.each do |c|                        
+                        if c.kind_of?(reqd_class)
+                            reqd_obj << c
+                        end
+                    end
+                end
+                return reqd_obj
+            end       
+
+=begin rdoc
+    Check if the win element exists. If it doesn't then a 
+    ObjectNotFoundException is rasied
+=end
+            def assert_object_exists()
+                if @hwnd == -1 
+                    raise ObjectNotFoundException.new("cannot find #{win_class}")
+                end
+            end
+            
+=begin rdoc
+    Is the current window a parent object? Return true
+    if yes, false if not. 
+=end
+            def is_parent()
+                assert_object_exists
+                return !@is_child
+            end
+            
+=begin rdoc
+        Does this element have a tab stop? If an element has a
+        tab stop, then when you keep pressing the tab button, at
+        some stage the focus will stop at this control. If this property
+        is not set, then the element wont receive focus when you keep 
+        pressing tab. 
+=end
+            def is_tab_stop()
+                assert_object_exists
+                return @is_tab_stop 
+            end
+            
+=begin rdoc
+    Get if the passed style has been defined for the Window or
+    not. The following styles are understood :        
+=end
+            def is_style(style)
+                assert_object_exists
+                find_styles()
+                eval_string = "@is_#{style}"
+                ret_val = eval eval_string
+                return ret_val
+            end
+            
+=begin rdoc
+    Is this control being used to display text? if yes, 
+    what is it
+    This method is to be overriden by controls that intend
+    to display text
+=end
+            def display_text()
+                assert_object_exists
+                return ""
+            end
+    
+            def to_s()
+                str = "Window(class:="
+                str = str + win_class()
+                str = str + ")" 
+                return str 
+            end
+            
+            ## The following methods are interfaces to the scripting world
+            ## The different window objects are retreived in a style such that
+            ## the script looks object oriented
+=begin rdoc
+        Get a Label element that is a child of the current window. 
+        Label's are the Static text elements that are usually used either to 
+        identify another control or simply display some text. 
+        
+        The props parameter is a hashtable of expected properties' name / value. 
+        
+        In the current version the following properties can be used:
+        1) 'text' -  The caption of the label. 
+        The value for text can either be a literal string or a regex. 
+        
+        eg:- 
+        If you say myWindow.win_label("text" => "Are you sure"), the the method
+        will return the WinLabel element whose caption is 'Are you sure'. If no such
+        element is found, the method returns an 'empty' WinLabel
+=end
+            def win_label(props)
+                assert_object_exists
+                return find_element(props, "WinLabel", ["text"])
+            end
+
+=begin rdoc
+        Get a WinEdit element that is a child of the current window. 
+        WinEdits are nothing but TextFields
+        
+        The props parameter is a hashtable of expected properties' name / value. 
+        
+        In the current version the following properties can be used:
+        1) 'label' -  The caption of the WinLabel element that is associated with this
+        control. Most WinEdit elements have a Static element beside the Edit that
+        describes what should be entered in the Edit box. This static element is 
+        considered to be the label for this WinEdit
+        The value for label  can either be a literal string or a regex. 
+        
+        eg:- 
+        If you say myWindow.win_edit("label" => "&Enter your name"), then the method
+        will return the WinEdit element whose label  'Enter your name'. If no such
+        element is found, the method returns an 'empty' WinEdit
+=end
+            def win_edit(props)
+                assert_object_exists
+                return find_element(props, "WinEdit", ["label"])
+            end
+  
+  
+=begin rdoc
+        Get a WinCombobox element that is a child of the current window.         
+        
+        The props parameter is a hashtable of expected properties' name / value. 
+        
+        In the current version the following properties can be used:
+        1) 'label' -  The caption of the WinLabel element that is associated with this
+        control. Most WinComboboxes elements have a Static element beside thecontrol that
+        describes what should be entered in the Combo box. This static element is 
+        considered to be the label for this control
+        The value for label  can either be a literal string or a regex. 
+        
+        eg:- 
+        If you say myWindow.win_combobox("label" => "&select your age"), then the method
+        will return the WinCombobox element whose label  'select your age'. If no such
+        element is found, the method returns an 'empty' WinEdit
+=end
+            def win_combobox(props)
+                assert_object_exists
+                return find_element(props, "WinComboBox", ["label"])
+            end
+
+=begin rdoc
+        Get a WinCheckbox element that is a child of the current window.         
+        
+        The props parameter is a hashtable of expected properties' name / value. 
+        
+        In the current version the following properties can be used:
+        1) 'text' -  The text displayed for the WinCheckbox
+        The value for text can either be a literal string or a regex. 
+        
+        eg:- 
+        If you say myWindow.win_checkbox("label" => "I agree"), then the method
+        will return the WinCheckbox element whose text is 'I agree'. If no such
+        element is found, the method returns an 'empty' WinCheckbox
+=end
+            def win_checkbox(props)
+                assert_object_exists
+                return find_element(props, "WinCheckbox", ["text"])
+            end
+
+=begin rdoc
+        Get a WinRadio element that is a child of the current window.         
+        
+        The props parameter is a hashtable of expected properties' name / value. 
+        
+        In the current version the following properties can be used:
+        1) 'text' -  The text displayed for the WinRadio
+        The value for text can either be a literal string or a regex. 
+        
+        eg:- 
+        If you say myWindow.win_radio("text" => "10 to 100"), then the method
+        will return the WinRadio element whose text is '10 to 100'. If no such
+        element is found, the method returns an 'empty' WinRadio
+=end            
+            def win_radio(props)
+                assert_object_exists
+                return find_element(props, "WinRadio", ["text"])
+            end
+
+
+=begin rdoc
+        Get a WinButton element that is a child of the current window.         
+        
+        The props parameter is a hashtable of expected properties' name / value. 
+        
+        In the current version the following properties can be used:
+        1) 'text' -  The text displayed for the WinButton
+        The value for text can either be a literal string or a regex. 
+        
+        eg:- 
+        If you say myWindow.win_button("text" => "OK"), then the method
+        will return the WinButton element whose text is 'OK'. If no such
+        element is found, the method returns an 'empty' WinButton
+=end      
+            def win_button(props)
+                assert_object_exists
+                return find_element(props, "WinButton", ["text"])
+            end                 
+            
+=begin rdoc
+=end
+            def debug()            
+                puts "#{to_s()}\n----- Styles ------------"
+                
+                puts "------Window type---------------"
+                ["overlapped", "popup", "child"].each do |s|
+                    puts "#{s} = #{is_style(s)}"
+                end
+                
+                
+                puts "----- Window visual properties----"
+                [ "border", "dlg_frame", "maximizable", "minimizable", \
+                    "v_scroll", "h_scroll", "sysmenu", "sizable" ].each do |s| 
+                    puts "#{s} = #{is_style(s)}"
+                end
+                
+                puts "------ current window state-------"
+                ["maximized", "minimized", "visible", "disabled"].each do |s|
+                    puts "#{s} = #{is_style(s)}"
+                end
+                
+                puts "------- other properties --------"
+                ["tab_stop"].each do |s|
+                    puts "#{s} = #{is_style(s)}"
+                end
+    
+                puts " --------------- End Style -------------------- "
+            end
+
+            protected
+=begin rdoc
+    If this element has another static text as its label, 
+    that needs to be set
+=end
+            def set_label(l)
+                assert_object_exists
+                @label_element = l
+            end
+            
+=begin rdoc
+    What is the label for the element? This is not valid 
+    for all types of element. Classes for whom this matter should
+    override this method. 
+=end
+            def label()
+                assert_object_exists
+                lbl = nil
+                if @label_element != nil
+                    lbl = @label_element.text
+                end
+                return lbl 
+            end
+            
+            protected 
+            def get_win_style()
+                find_styles()
+                return @control_style
+            end
+
+            private
+            def find_styles()
+                
+                control_style = get_window_style(@hwnd)
+                @control_style = control_style
+                #Styles that the determine the type of wiindow
+                @is_overlapped = control_style & WS_OVERLAPPED  == WS_OVERLAPPED
+                @is_popup = control_style & WS_POPUP    == WS_POPUP
+                @is_child = control_style & WS_CHILD == WS_CHILD
+
+                #Styles to determine the physical appearance of the window. 
+                @is_border = control_style & WS_BORDER == WS_BORDER
+                @is_dlg_frame = control_style & WS_DLGFRAME == WS_DLGFRAME
+                @is_v_scroll = control_style & WS_VSCROLL == WS_VSCROLL
+                @is_h_scroll = control_style & WS_HSCROLL == WS_HSCROLL
+                @is_maximizable = control_style & WS_MAXIMIZEBOX == WS_MAXIMIZEBOX
+                @is_minimizable = control_style & WS_MINIMIZEBOX == WS_MINIMIZEBOX
+                @is_sysmenu = control_style & WS_SYSMENU == WS_SYSMENU
+                @is_sizable = control_style & WS_THICKFRAME == WS_THICKFRAME
+
+
+                #Styles that determine the current state of the window
+                @is_minimized = control_style & WS_MINIMIZE == WS_MINIMIZE
+                @is_maximized = control_style & WS_MAXIMIZE == WS_MAXIMIZE                
+                @is_visible = control_style & WS_VISIBLE == WS_VISIBLE
+                @is_disabled = control_style & WS_DISABLED == WS_DISABLED
+                
+                # Does circulating through the tab button, stop at this control at any stage?
+                @is_tab_stop = control_style & WS_TABSTOP == WS_TABSTOP
+                
+                
+            end
+            
+            def find_children()
+                hwnd = @hwnd
+                elems = children(hwnd) 
+                mark_for_deletion=[]
+                elems.each do |c| 
+                    win_class = class_name(c)
+                    if TextUtils.compare_text(win_class, /^Combo/)
+                        gc_count=0
+                        gc = children(c)
+                        gc_count = gc.length 
+                        gc.each do |c2|
+                            mark_for_deletion << c2
+                        end
+                    end
+                end
+                
+                
+                mark_for_deletion.each do |m|
+                    elems.delete(m) 
+                end
+                
+                all_children=[]
+                all_labelled  = []
+                
+                #Even though it may take slightly longer, it 
+                #definitely is much less buggier to loop through 
+                #the elements multiple times
+                elems.each do |c|
+                    elem =  Window::create(c)    
+                    #keep track of those windows are labels for others
+                    
+                    if elem.instance_of?(WinLabel)        
+                        labelled = elem.labelled_control()        
+                        if labelled != nil && labelled.exists?()
+                            all_labelled << labelled
+                        end        
+                    end
+                end    
+                
+                elems.each do |c| 
+                    mark_for_delete = []
+                    elem =  Window::create(c)    
+                    elem_to_add = nil
+                    
+                    all_labelled.each do |l|
+                        if l.hwnd == c
+                            mark_for_delete << l
+                            if elem_to_add == nil
+                                elem_to_add = l 
+                                break 
+                            end
+                        end
+                    end
+                    
+                    mark_for_delete.each do |m|
+                        all_labelled.delete(m)
+                    end
+                    
+                    if elem_to_add == nil
+                        elem_to_add = elem
+                    end                
+                    all_children << elem_to_add                    
+                end    
+                return all_children
+            end
+            
+            ## Helper method used by the accessors. 
+            def find_element(props, reqd_class, prop_names) 
+                #prop_names = ["text"]
+                #reqd_class = "WinLabel"
+                #in this version only one property is allowd 
+                def_prop = prop_names[0]
+    
+                CompileUtils.assert_argument_types(Hash, props.class)             
+                CompileUtils.assert_argument_types(Array, prop_names.class) 
+                
+                found_elem = eval "#{reqd_class}.new(-1)"
+                
+                if props.length == 1 && props[def_prop] != nil
+                    exp_text = props[def_prop]                
+                    
+                    reqd_elems = child_objects(found_elem.class) 
+                    reqd_elems.each do |e|
+                        eval_string = "e.#{def_prop}"
+                        act_text = eval eval_string
+                        if TextUtils.compare_text(act_text, exp_text) 
+                            found_elem = e
+                            break 
+                        else
+                            #puts "reqd=#{exp_text}; act=#{act_text}"
+                        end
+                    end                
+                else
+                    raise UnsupportedOperationException.new("Limited search options available now")
+                end
+                return found_elem
+            end
+            
+        end
+    end    
+end
+
+