win 0.3.17 → 0.3.24

data/lib/win/gui/message.rb

@@ -7,7 +7,7 @@ module Win
     #  Below is a table of system-defined message prefixes:
     #
     #  *Prefix*:: *Message* *category* 
-    #  ABM:: Application desktop toolbar
+    #  ABM:: App desktop toolbar
     #  BM:: Button control
     #  CB:: Combo box control
     #  CBEM:: Extended combo box control
@@ -157,7 +157,7 @@ module Win
       WM_IME_KEYLAST                = 0x010F
       WM_INITDIALOG                 = 0x0110
       WM_COMMAND                    = 0x0111
-      # Windows Message Sys Command
+      # Windows Message System Command (emitted by Window/System menu)
       WM_SYSCOMMAND                 = 0x0112
       WM_TIMER                      = 0x0113
       WM_HSCROLL                    = 0x0114
@@ -337,22 +337,22 @@ module Win
 
       # The MSG structure contains message information from a thread's message queue.
       #
-      #  typedef struct {
-      #     HWND hwnd;
-      #     UINT message;
-      #     WPARAM wParam;
-      #     LPARAM lParam;
-      #     DWORD time;
-      #     POINT pt;
-      #  } MSG, *PMSG;
-      #
-      #  hwnd:: Handle to the window whose window procedure receives the message. NULL when the message is a thread message.
-      #  message:: Message identifier. Applications can only use the low word; the high word is reserved by the system.
-      #  wParam:: Additional info about the message. Exact meaning depends on the value of the message member.
-      #  lParam:: Additional info about the message. Exact meaning depends on the value of the message member.
-      #  time:: Specifies the time at which the message was posted.
-      #  pt:: POINT structure - the cursor position, in screen coordinates, when the message was posted.
-      #       (in my definition, it is changed to two longs: x, y - has the same effect, just avoid nested structs)
+      # typedef struct {
+      #    HWND hwnd;
+      #    UINT message;
+      #    WPARAM wParam;
+      #    LPARAM lParam;
+      #    DWORD time;
+      #    POINT pt;
+      # } MSG, *PMSG;
+      #
+      # hwnd:: Handle to the window whose window procedure receives the message. NULL when the message is a thread message.
+      # message:: Message identifier. Apps can only use the low word; the high word is reserved by the system.
+      # wParam:: Additional info about the message. Exact meaning depends on the value of the message member.
+      # lParam:: Additional info about the message. Exact meaning depends on the value of the message member.
+      # time:: Specifies the time at which the message was posted.
+      # pt:: POINT structure - the cursor position, in screen coordinates, when the message was posted.
+      #      (in my definition, it is changed to two longs: x, y - has the same effect, just avoid nested structs)
       class Msg < FFI::Struct
         layout :hwnd, :ulong,
                :message, :uint,
@@ -364,9 +364,9 @@ module Win
       end
 
       ##
-      # The SendAsyncProc function is an application-defined callback function used with the SendMessageCallback
+      # The SendAsyncProc function is an App-defined callback function used with the SendMessageCallback
       # function. The system passes the message to the callback function after passing the message to the
-      # destination window procedure. SendAsyncProc is a placeholder for the application-defined function name.
+      # destination window procedure. SendAsyncProc is a placeholder for the App-defined function name.
       #
       # [*Syntax*] VOID SendAsyncProc( HWND hwnd, UINT uMsg, ULONG_PTR dwData, LRESULT lResult );
       #
@@ -374,7 +374,7 @@ module Win
       #        function was called with its hwnd parameter set to HWND_BROADCAST, the system calls the
       #        SendAsyncProc function once for each top-level window.
       # uMsg:: <in> Specifies the message.
-      # dwData:: <in> Specifies an application-defined value sent from the SendMessageCallback function.
+      # dwData:: <in> Specifies an App-defined value sent from the SendMessageCallback function.
       # lResult:: <in> Specifies the result of the message processing. This value depends on the message.
       #
       # :call-seq:
@@ -386,7 +386,7 @@ module Win
       #  The SendMessageCallback function sends the specified message to a window or windows. It calls the window
       #  procedure for the specified window and returns immediately. After the window procedure processes the message,
       #  the system calls the specified callback function, passing the result of the message processing and an
-      #  application-defined value to the callback function.
+      #  App-defined value to the callback function.
       #
       #  [*Syntax*] BOOL SendMessageCallback( HWND hWnd, UINT Msg, WPARAM wParam, LPARAM lParam,
       #             SENDASYNCPROC lpCallBack, ULONG_PTR dwData);
@@ -400,7 +400,7 @@ module Win
       #  lpCallBack:: <in> Pointer to a callback function that the system calls after the window procedure processes
       #               the message. For more information, see SendAsyncProc. If hWnd is HWND_BROADCAST, the system calls
       #               SendAsyncProc callback function once for each top-level window.
-      #  dwData:: <in> Specifies an application-defined value to be sent to the callback function pointed to by
+      #  dwData:: <in> Specifies an App-defined value to be sent to the callback function pointed to by
       #           the lpCallBack parameter.
       #  *Returns*:: Nonzero if the function succeeds, zero if it fails. For extended error info, call GetLastError.
       #  ---
@@ -409,8 +409,8 @@ module Win
       #    SendNotifyMessage, and SendMessageCallback), its message parameters cannot include pointers. Otherwise,
       #    the operation will fail. The functions will return before the receiving thread has had a chance
       #    to process the message and the sender will free the memory before it is used.
-      #  - Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function
-      #    to obtain a unique message for inter-application communication.
+      #  - Apps that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function
+      #    to obtain a unique message for inter-App communication.
       #  - The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send
       #    messages (>= WM_USER) to another process, you must do custom marshalling.
       #  - The callback function is called only when the thread that called SendMessageCallback also calls GetMessage,
@@ -448,8 +448,8 @@ module Win
       # - Microsoft Windows Vista and later. When a message is blocked by UIPI the last error, retrieved with
       #   GetLastError, is set to 5 (access denied). Messages in a message queue are retrieved by calls to the
       #   GetMessage or PeekMessage function.
-      # - Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function
-      #   to obtain a unique message for inter-application communication.
+      # - Apps that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function
+      #   to obtain a unique message for inter-App communication.
       # - The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
       #   messages (those >= WM_USER) to another process, you must do custom marshalling.
       # - If you send a message in the range below WM_USER to the asynchronous message functions (PostMessage,
@@ -492,8 +492,8 @@ module Win
       # *Remarks*:
       # - Microsoft Windows Vista and later. When a message is blocked by UIPI the last error, retrieved with
       #   GetLastError, is set to 5 (access denied).
-      # - Applications that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function
-      #   to obtain a unique message for inter-application communication.
+      # - Apps that need to communicate using HWND_BROADCAST should use the RegisterWindowMessage function
+      #   to obtain a unique message for inter-App communication.
       # - The system only does marshalling for system messages (those in the range 0 to (WM_USER-1)). To send other
       #   messages (those >= WM_USER) to another process, you must do custom marshalling.
       # - If the specified window was created by the calling thread, the window procedure is called immediately as
@@ -549,7 +549,7 @@ module Win
       # *Warning*
       # Because the return value can be nonzero, zero, or -1, avoid code like this:
       #   while (GetMessage( lpMsg, hWnd, 0, 0)) ...
-      # The possibility of a -1 return value means that such code can lead to fatal application errors.
+      # The possibility of a -1 return value means that such code can lead to fatal App errors.
       # Instead, use code like this:
       #   while( (bRet = GetMessage( msg, hWnd, 0, 0 )) != 0)
       #     if (bRet == -1)
@@ -561,12 +561,12 @@ module Win
       #   end
       # ---
       # *Remarks*:
-      # An application typically uses the return value to determine whether to end the main message loop and
+      # An App typically uses the return value to determine whether to end the main message loop and
       # exit the program.
       #
       # The GetMessage function retrieves messages associated with the window identified by the hWnd parameter
       # or any of its children, as specified by the IsChild function, and within the range of message values
-      # given by the wMsgFilterMin and wMsgFilterMax parameters. Note that an application can only use the low
+      # given by the wMsgFilterMin and wMsgFilterMax parameters. Note that an App can only use the low
       # word in the wMsgFilterMin and wMsgFilterMax parameters; the high word is reserved for the system.
       # Note that GetMessage always retrieves WM_QUIT messages, no matter which values you specify for
       # wMsgFilterMin and wMsgFilterMax.
@@ -590,7 +590,7 @@ module Win
       # Windows XP: If a top-level window stops responding to messages for more than several seconds, the 
       # system considers the window to be not responding and replaces it with a ghost window that has the same
       # z-order, location, size, and visual attributes. This allows the user to move it, resize it, or even
-      # close the application. However, these are the only actions available because the application is
+      # close the App. However, these are the only actions available because the App is
       # actually not responding. When in the debugger mode, the system does not generate a ghost window.
       # ---
       # <b>Enhanced (snake_case) API: makes all args optional, returns: *false* if WM_QUIT was posted,
@@ -650,7 +650,7 @@ module Win
       # *Remarks*:
       # PeekMessage retrieves messages associated with the window identified by the hWnd parameter or any of
       # its children as specified by the IsChild function, and within the range of message values given by the
-      # wMsgFilterMin and wMsgFilterMax parameters. Note that an application can only use the low word in the
+      # wMsgFilterMin and wMsgFilterMax parameters. Note that an App can only use the low word in the
       # wMsgFilterMin and wMsgFilterMax parameters; the high word is reserved for the system.
       #
       # Note that PeekMessage always retrieves WM_QUIT messages, no matter which values you specify for
@@ -677,8 +677,8 @@ module Win
       # Windows XP: If a top-level window stops responding to messages for more than several seconds, the
       # system considers the window to be not responding and replaces it with a ghost window that has the same
       # z-order, location, size, and visual attributes. This allows the user to move it, resize it, or even
-      # close the application. However, these are the only actions available because the application is
-      # actually not responding. When an application is being debugged, the system does not generate a ghost
+      # close the App. However, these are the only actions available because the App is
+      # actually not responding. When an App is being debugged, the system does not generate a ghost
       # window.
       # ---
       # <b>Enhanced (snake_case) API: makes all args optional, returns *nil* if no message in queue,
@@ -718,12 +718,12 @@ module Win
       # TranslateMessage produces WM_CHAR messages only for keys that are mapped to ASCII characters by the
       # keyboard driver.
       #
-      # If applications process virtual-key messages for some other purpose, they should not call
-      # TranslateMessage. For instance, an application should not call TranslateMessage if the
-      # TranslateAccelerator function returns a nonzero value. Note that the application is responsible for
-      # retrieving and dispatching input messages to the dialog box. Most applications use the main message
+      # If Apps process virtual-key messages for some other purpose, they should not call
+      # TranslateMessage. For instance, an App should not call TranslateMessage if the
+      # TranslateAccelerator function returns a nonzero value. Note that the App is responsible for
+      # retrieving and dispatching input messages to the dialog box. Most Apps use the main message
       # loop for this. However, to permit the user to move to and to select controls by using the keyboard,
-      # the application must call IsDialogMessage. For more information, see Dialog Box Keyboard Interface.
+      # the App must call IsDialogMessage. For more information, see Dialog Box Keyboard Interface.
       # ---
       # <b>Enhanced (snake_case) API: returns true/false instead of nonzero/zero</b>
       #
@@ -748,9 +748,9 @@ module Win
       # message and the lParam parameter of the WM_TIMER message is not NULL, lParam points to a function that
       # is called instead of the window procedure.
       #
-      # Note that the application is responsible for retrieving and dispatching input messages to the dialog
-      # box. Most applications use the main message loop for this. However, to permit the user to move to and
-      # to select controls by using the keyboard, the application must call IsDialogMessage. For more
+      # Note that the App is responsible for retrieving and dispatching input messages to the dialog
+      # box. Most Apps use the main message loop for this. However, to permit the user to move to and
+      # to select controls by using the keyboard, the App must call IsDialogMessage. For more
       # information, see Dialog Box Keyboard Interface.
       # ---
       # <b>Enhanced (snake_case) API: </b>

data/lib/win/gui/window.rb

@@ -229,7 +229,7 @@ module Win
       # :call-seq:
       #   win_handle = find_window( class_name, win_name )
       #
-      function :FindWindow, [:pointer, :pointer], :HWND, zeronil: true
+      function :FindWindow, [:pointer, :pointer], :HWND, fails: 0
 
       ##
       # Unicode version of FindWindow (strings must be encoded as utf-16LE AND terminate with "\x00\x00")
@@ -237,7 +237,7 @@ module Win
       # :call-seq:
       #   win_handle = find_window_w( class_name, win_name )
       #
-      function :FindWindowW, [:pointer, :pointer], :HWND, zeronil: true
+      function :FindWindowW, [:pointer, :pointer], :HWND, fails: 0
 
       ##
       #  The FindWindowEx function retrieves a handle to a window whose class name and window name match the specified
@@ -284,7 +284,7 @@ module Win
       # :call-seq:
       #   win_handle = find_window_ex( win_handle, after_child, class_name, win_name )
       #
-      function :FindWindowEx, [:HWND, :HWND, :pointer, :pointer], :HWND, zeronil: true
+      function :FindWindowEx, [:HWND, :HWND, :pointer, :pointer], :HWND, fails: 0
 
       ##
       # GetWindowText returns the text of the specified window's title bar (if it has one).
@@ -632,7 +632,7 @@ module Win
       #:call-seq:
       #   win_handle = [get_]foreground_window()
       #
-      function :GetForegroundWindow, [], :HWND, zeronil: true
+      function :GetForegroundWindow, [], :HWND, fails: 0
 
       ##
       # SetForegroundWindow function puts the thread that created the specified window into the foreground
@@ -705,7 +705,7 @@ module Win
       #:call-seq:
       #   win_handle = [get_]active_window()
       #
-      function :GetActiveWindow, [], :HWND, zeronil: true
+      function :GetActiveWindow, [], :HWND, fails: 0
 
       ##
       # The GetWindow function retrieves a handle to a window that has the specified relationship (Z-Order or
@@ -762,7 +762,7 @@ module Win
       # :call-seq:
       #  window_handle = get_window(h_wnd, u_cmd)
       #
-      function :GetWindow, [:HWND, :UINT], :HWND, zeronil: true
+      function :GetWindow, [:HWND, :UINT], :HWND, fails: 0
 
       ##
       # The GetParent function retrieves a handle to the specified window's parent OR OWNER.
@@ -788,7 +788,7 @@ module Win
       # :call-seq:
       #  parent = get_parent(h_wnd)
       #
-      function :GetParent, [:HWND], :HWND, zeronil: true
+      function :GetParent, [:HWND], :HWND, fails: 0
 
       ##
       # The GetAncestor function retrieves the handle to the ancestor of the specified window.
@@ -810,7 +810,7 @@ module Win
       # :call-seq:
       #  ancestor = get_ancestor(hwnd, ga_flags)
       #
-      function :GetAncestor, [:HWND, :UINT], :HWND, zeronil: true
+      function :GetAncestor, [:HWND, :UINT], :HWND, fails: 0
 
 
       # Convenience wrapper methods:

data/lib/win/library.rb

@@ -281,7 +281,7 @@ module Win
     # :camel_only:: If true, no snake_case method is defined
     # :alias(es):: Provides additional alias(es) for defined method
     # :boolean:: Forces method to return true/false instead of nonzero/zero
-    # :zeronil:: Forces method to return nil if function result is zero
+    # :fails:: Forces method to return nil if function result is equal to following error code
     #
     def function(name, params, returns, options={}, &def_block)
       snake_name, camel_name, effective_names, aliases = generate_names(name, options)
@@ -394,20 +394,20 @@ module Win
     end
 
     # Generates body for snake_case method according to directives contained in options
-    # options (:boolean, :zeronil) currently supported
+    # options (:boolean, :fails) currently supported
     #
     def generate_snake_method_body(api, options, &def_block)
       if def_block
-        if options[:zeronil]
-          ->(*args, &block){ (res = def_block.(api, *args, &block)) != 0 ? res : nil }
+        if options[:fails]
+          ->(*args, &block){ (res = def_block.(api, *args, &block)) == options[:fails] ? nil: res }
         elsif options[:boolean]
           ->(*args, &block){ def_block.(api, *args, &block) != 0 }
         else
           ->(*args, &block){ def_block.(api, *args, &block) }
         end
       else
-        if options[:zeronil]
-          ->(*args, &block){ (res = block ? block[api.call(*args)] : api.call(*args)) != 0 ? res : nil }
+        if options[:fails]
+          ->(*args, &block){ (res = block ? block[api.call(*args)] : api.call(*args)) == options[:fails] ? nil : res }
         elsif options[:boolean]
           ->(*args, &block){ block ? block[api.call(*args)] : api.call(*args) != 0 }
         else

data/spec/spec_helper.rb

@@ -83,7 +83,7 @@ module WinTest
   IMPOSSIBLE = 'Impossible'
   CONVERSION_ERROR = /Can.t convert/
   SLEEP_DELAY = 0.02
-  APP_PATH = File.join(File.dirname(__FILE__), "test_apps/locknote/LockNote.exe" )
+  APP_PATH = File.join(File.dirname(__FILE__), "../misc/locknote/LockNote.exe" )
   APP_START = cygwin? ? "cmd /c start `cygpath -w #{APP_PATH}`" : 'start "" "' + APP_PATH + '"'
   WIN_TITLE = 'LockNote - Steganos LockNote'
   WIN_RECT = [710, 400, 1210, 800]
@@ -123,7 +123,9 @@ module WinTestApp
     textarea = find_window_ex(handle, 0, TEXTAREA_CLASS, nil)
     app = "Locknote" # App identifier
 
-    eigen_class = class << app; self; end      # Extracting app's eigenclass
+    eigen_class = class << app;
+      self;
+    end      # Extracting app's eigenclass
     eigen_class.class_eval do                  # Defining singleton methods on app
       define_method(:handle) {handle}
       define_method(:textarea) {textarea}
@@ -136,7 +138,10 @@ module WinTestApp
     while @launched_test_app && find_window(nil, WIN_TITLE)
       shut_window @launched_test_app.handle
       sleep SLEEP_DELAY
-      keystroke('N') if find_window(nil, "Steganos Locknote") # Dealing with closing modal dialog
+      if dialog = find_window(nil, "Steganos Locknote") # Dealing with closing modal dialog
+        set_foreground_window(dialog)
+        keystroke('N')
+      end
     end
     @launched_test_app = nil
   end
@@ -148,6 +153,23 @@ module WinTestApp
     close_test_app
   end
 
+  def test_app_with_dialog(type=:close)
+    test_app do |app|
+      case type
+        when :close
+          keystroke('A')
+          shut_window app.handle
+          sleep 0.01 until dialog = find_window(nil, "Steganos Locknote")
+        when :save
+          keystroke(VK_ALT, 'F', 'A')
+          sleep 0.01 until dialog = find_window(nil, "Save As")
+      end
+      yield app, dialog
+      set_foreground_window(dialog)
+      keystroke(VK_ESCAPE)
+    end
+  end
+
   # Emulates combinations of (any amount of) keys pressed one after another (Ctrl+Alt+P) and then released
   # *keys should be a sequence of a virtual-key codes. These codes must be a value in the range 1 to 254.
   # For a complete list, see msdn:Virtual Key Codes.

data/spec/win/gui/dialog_spec.rb

@@ -6,22 +6,6 @@ module WinGuiDialogTest
   include WinTestApp
   include Win::Gui::Dialog
 
-  def test_app_with_dialog(type=:close)
-    test_app do |app|
-      case type
-        when :close
-          keystroke('A')
-          shut_window app.handle
-          sleep 0.01 until dialog = find_window(nil, "Steganos Locknote")
-        when :save
-          keystroke(VK_ALT, 'F', 'A')
-          sleep 0.01 until dialog = find_window(nil, "Save As")
-      end
-      yield app, dialog
-      keystroke(VK_ESCAPE)
-    end
-  end
-
   describe Win::Gui::Dialog do
 
     describe "#message_box" do

data/spec/win/gui/input_spec.rb

@@ -6,22 +6,18 @@ module WinGuiInputTest
   include WinTestApp
   include Win::Gui::Input
 
+  # rolling back changes with Ctrl-Z to allow window closing without dialog!
+  def rollback_changes(num_changes)
+    num_changes.times {keystroke(VK_CONTROL, 'Z'.ord)}
+  end
+
   describe Win::Gui::Input, ' defines a set of API functions related to user input' do
 
     describe '#keydb_event' do
       spec{ use{ keybd_event(vkey = 0, bscan = 0, flags = 0, extra_info = 0) }}
       before(:each){ (@app=launch_test_app)}
       after(:each) do
-        3.times do  # rolling back changes to allow window closing without dialog!
-          keybd_event(VK_CONTROL, 0, KEYEVENTF_KEYDOWN, 0)
-          sleep KEY_DELAY
-          keybd_event('Z'.ord, 0, KEYEVENTF_KEYDOWN, 0)
-          sleep KEY_DELAY
-          keybd_event('Z'.ord, 0, KEYEVENTF_KEYUP, 0)
-          sleep KEY_DELAY
-          keybd_event(VK_CONTROL, 0, KEYEVENTF_KEYUP, 0)
-          sleep KEY_DELAY
-        end
+        rollback_changes(3)
         close_test_app
       end
 

data/spec/win/gui/menu_spec.rb

@@ -0,0 +1,291 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+require 'win/gui/menu'
+
+module WinGuiWindowTest
+
+  include WinTestApp
+  include Win::Gui::Window
+
+  describe Win::Gui::Menu, ' defines a set of API functions related to menus' do
+    context 'non-destructive methods' do
+      before(:all)do
+        @app = launch_test_app
+        @menu = get_menu(@app.handle)
+        @file_menu = get_sub_menu(@menu, 0)
+      end
+      after(:all){ close_test_app if @launched_test_app }
+
+      describe "#get_menu" do
+
+        spec{ use{ menu = GetMenu(@app.handle) }}
+        spec{ use{ menu = get_menu(@app.handle) }}
+
+        it "retrieves a handle to the menu assigned to the specified top-level window" do
+          menu1 = GetMenu(@app.handle)
+          menu2 = get_menu(@app.handle)
+          menu1.should be_an Integer
+          menu1.should == @menu
+          menu1.should == menu2
+        end
+
+        it "returns 0/nil if no menu assigned to the specified top-level window" do
+          test_app_with_dialog(:close) do |app, dialog|
+            GetMenu(dialog).should == 0
+            get_menu(dialog).should == nil
+          end
+        end
+      end # describe get_menu
+
+      describe "#get_system_menu" do
+        spec{ use{ system_menu = GetSystemMenu(any_handle, reset=0) }}
+        spec{ use{ system_menu = get_system_menu(any_handle, reset=false) }}
+
+        it "with reset=0/false(default) allows the application to access the window menu (AKA system menu)" do
+          menu1 = GetSystemMenu(@app.handle, reset=0)
+          menu2 = get_system_menu(@app.handle, reset=0)
+          menu3 = get_system_menu(@app.handle)
+          menu1.should be_an Integer
+          menu1.should == menu2
+          menu1.should == menu3
+        end
+
+        it "with reset=1/true allows the application to reset its window menu to default, returns 0/nil" do
+          GetSystemMenu(@app.handle, reset=1).should == 0
+          get_system_menu(@app.handle, reset=true).should == nil
+        end
+      end # describe get_system_menu
+
+      describe "#get_menu_item_count" do
+
+        spec{ use{ num_items = GetMenuItemCount(@menu) }}
+        spec{ use{ num_items = get_menu_item_count(@menu) }}
+
+        it "determines the number of items in the specified menu. " do
+          GetMenuItemCount(@menu).should == 3
+          get_menu_item_count(@menu).should == 3
+        end
+
+        it "returns -1/nil if function fails " do
+          GetMenuItemCount(not_a_handle).should == -1
+          get_menu_item_count(not_a_handle).should == nil
+        end
+      end # describe get_menu_item_count
+
+      describe "#get_menu_item_id" do
+        spec{ use{ item_id = GetMenuItemID(@menu, pos=0) }}
+        spec{ use{ item_id = get_menu_item_id(@menu, pos=0) }}
+
+        it "retrieves the menu item identifier of a menu item located at the specified position" do
+          GetMenuItemID(@file_menu, pos=0).should == ID_FILE_SAVE_AS
+          get_menu_item_id(@file_menu, pos=0).should == ID_FILE_SAVE_AS
+        end
+
+        it "returns -1/nil if no menu item at given position" do
+          GetMenuItemID(@menu, pos=4).should == -1
+          get_menu_item_id(@menu, pos=4).should == nil
+        end
+
+        it "returns -1/nil if given menu item is in fact a sub-menu" do
+          GetMenuItemID(@menu, pos=0).should == -1
+          get_menu_item_id(@menu, pos=1).should == nil
+        end
+      end # describe get_menu_item_id
+
+      describe "#get_sub_menu" do
+        spec{ use{ sub_menu = GetSubMenu(@menu, pos=0) }}
+        spec{ use{ sub_menu = get_sub_menu(@menu, pos=0) }}
+
+        it "retrieves a handle to the drop-down menu or submenu activated by the specified menu item" do
+          sub_menu1 = GetSubMenu(@menu, pos=0)
+          sub_menu2 = get_sub_menu(@menu, pos=0)
+          sub_menu1.should be_an Integer
+          sub_menu1.should == @file_menu
+          sub_menu1.should == sub_menu2
+        end
+
+        it "returns 0/nil if unable to find submenu activated by the specified menu item" do
+          GetSubMenu(@file_menu, pos=0).should == 0
+          get_sub_menu(@file_menu, pos=0).should == nil
+        end
+      end # describe get_sub_menu
+
+      describe "#is_menu" do
+        before(:all){ @menu = get_menu(@app.handle) }
+
+        spec{ use{ success = IsMenu(@menu) }}
+        spec{ use{ success = menu?(@menu) }}
+
+        it "determines whether a given handle is a menu handle " do
+          IsMenu(@menu).should == 1
+          is_menu(@menu).should == true
+          menu?(@menu).should == true
+          menu?(@file_menu).should == true
+          IsMenu(not_a_handle).should == 0
+          is_menu(not_a_handle).should == false
+          menu?(not_a_handle).should == false
+        end
+      end # describe is_menu
+
+      describe "#set_menu" do
+        spec{ use{ success = SetMenu(window_handle=0, menu_handle=0) }}
+        spec{ use{ success = set_menu(window_handle=0, menu_handle=0) }}
+
+        it "assigns/removes menu of the specified top-level window" do
+          SetMenu(@app.handle, menu_handle=0)
+          get_menu(@app.handle).should == nil
+          SetMenu(@app.handle, @menu)
+          menu(@app.handle).should == @menu
+          set_menu(@app.handle)
+          menu(@app.handle).should == nil
+          set_menu(@app.handle, @menu)
+          menu(@app.handle).should == @menu
+        end
+
+        it "snake_case api with nil, zero or omitted menu_handle removes menu" do
+          [[@app.handle, 0], [@app.handle, nil], [@app.handle]].each do |args|
+            set_menu(*args)
+            menu(@app.handle).should == nil
+            set_menu(@app.handle, @menu)
+          end
+        end
+      end # describe set_menu
+
+      describe "#create_menu" do
+        after(:each){ destroy_menu(@new_menu) }
+
+        spec{ use{ @new_menu = CreateMenu() }}
+        spec{ use{ @new_menu = create_menu() }}
+
+        it "original api creates a menu. The menu is initially empty, but it can be filled with menu items" do
+          @new_menu = CreateMenu()
+          menu?(@new_menu).should == true
+        end
+
+        it "snake_case api creates a menu. The menu is initially empty." do
+          @new_menu = create_menu()
+          menu?(@new_menu).should == true
+        end
+      end # describe create_menu
+
+      context 'functions related to menu item manipulation' do
+        before(:each)do
+          @new_menu = create_menu()
+          @sub_menu = create_menu()
+          @text = FFI::MemoryPointer.from_string("Appended Item Text")
+        end
+        after(:each){ destroy_menu(@new_menu) }
+
+        describe "#append_menu" do
+          spec{ use{ success = AppendMenu(menu_handle=0, flags=0, id_new_item=0, lp_new_item=nil) }}
+          spec{ use{ success = append_menu(menu_handle=0, flags=0, id_new_item=0, lp_new_item=nil) }}
+
+          it "appends a new item to the end of the specified menu bar, drop-down or context menu, returns 1/true " do
+            AppendMenu(@new_menu, flags=MF_STRING, 333, @text).should == 1
+            append_menu(@new_menu, flags=MF_STRING, 333, @text).should == true
+            menu_item_count(@new_menu).should == 2
+            menu_item_id(@new_menu, pos=0).should == 333
+          end
+
+          it "appends a submenu to the end of the specified menu bar, drop-down or context menu, returns 1/true " do
+            AppendMenu(@new_menu, MF_STRING | MF_POPUP, @sub_menu, @text).should == 1
+            append_menu(@new_menu, MF_STRING | MF_POPUP, @sub_menu, @text).should == true
+            menu_item_count(@new_menu).should == 2
+            get_sub_menu(@new_menu, pos=0).should == @sub_menu
+            get_sub_menu(@new_menu, pos=1).should == @sub_menu
+          end
+
+          it "returns 0/false if unable to appends a new item to the end of the specified menu" do
+            AppendMenu(0, flags=MF_STRING, 333, @text).should == 0
+            append_menu(0, flags=MF_STRING, 333, @text).should == false
+          end
+        end # describe append_menu
+
+        describe "#insert_menu" do
+          before(:each)do
+            append_menu(@new_menu, MF_STRING, ID_FILE_SAVE_AS, FFI::MemoryPointer.from_string("Appended Item Text"))
+          end
+
+          spec{ use{ success = InsertMenu(menu_handle=0, position=0, flags=0, id_new_item=0, lp_new_item=nil) }}
+          spec{ use{ success = insert_menu(menu_handle=0, position=0, flags=0, id_new_item=0, lp_new_item=nil) }}
+
+          it "inserts a new menu item into a menu, moving other items down the menu, returns 0/true" do
+            InsertMenu(@new_menu, 0, MF_STRING | MF_BYPOSITION, 1, @text).should == 1
+            insert_menu(@new_menu, 0, MF_STRING | MF_BYPOSITION, 0, @text).should == true
+            menu_item_count(@new_menu).should == 3
+            menu_item_id(@new_menu, pos=0).should == 0
+            menu_item_id(@new_menu, pos=1).should == 1
+          end
+
+          it "returns 0/false if unable to appends a new item to the end of the specified menu" do
+            InsertMenu(0, 0, flags=MF_STRING, 333, @text).should == 0
+            insert_menu(0, 0, flags=MF_STRING, 333, @text).should == false
+          end
+        end # describe insert_menu
+
+        describe "#delete_menu" do
+          before(:each)do
+            append_menu(@new_menu, MF_STRING, 0, FFI::MemoryPointer.from_string("Item 0"))
+            append_menu(@new_menu, MF_STRING, 1, FFI::MemoryPointer.from_string("Item 1"))
+            append_menu(@new_menu, MF_POPUP | MF_STRING, @sub_menu, FFI::MemoryPointer.from_string("Sub 1"))
+          end
+
+          spec{ use{ success = DeleteMenu(menu_handle=0, position=0, flags=0) }}
+          spec{ use{ success = delete_menu(menu_handle=0, position=0, flags=0) }}
+
+          it "deletes an item from the specified menu, returns 1/true" do
+            DeleteMenu(@new_menu, position=0, flags=MF_BYPOSITION).should == 1
+            menu_item_count(@new_menu).should == 2
+            delete_menu(@new_menu, position=0, flags=MF_BYPOSITION).should == true
+            menu_item_count(@new_menu).should == 1
+          end
+
+          it "returns 0/false if unable to delete an item from the specified menu" do
+            DeleteMenu(@new_menu, position=5, flags=MF_BYPOSITION).should == 0
+            menu_item_count(@new_menu).should == 3
+            delete_menu(0, position=0, flags=MF_BYPOSITION).should == false
+          end
+
+          it "destroys the handle to submenu and frees the memory if given menu item opens a submenu" do
+            delete_menu(@new_menu, position=2, flags=MF_BYPOSITION).should == true
+            menu_item_count(@new_menu).should == 2
+            menu?(@sub_menu).should == false
+          end
+        end # describe delete_menu
+      end # functions related to menu item manipulation
+    end # context 'non-destructive methods'
+
+    context 'destructive methods' do
+      before(:each)do
+        @app = launch_test_app
+        @menu = get_menu(@app.handle)
+        @file_menu = get_sub_menu(@menu, 0)
+      end
+      after(:each){ close_test_app if @launched_test_app }
+
+      describe "#destroy_menu" do
+        spec{ use{ success = DestroyMenu(menu_handle=0) }}
+        spec{ use{ success = destroy_menu(menu_handle=0) }}
+
+        it "original api destroys the specified menu and frees any memory that the menu occupies, returns 1" do
+          DestroyMenu(@menu).should == 1
+          menu?(@menu).should == false
+        end
+
+        it "snake_case api destroys the specified menu and frees any memory that the menu occupies, returns true" do
+          destroy_menu(@menu).should == true
+          menu?(@menu).should == false
+        end
+
+        it "returns 0/false if function was not successful " do
+          destroy_menu(h_menu=0).should == false
+          DestroyMenu(0).should == 0
+        end
+      end # describe destroy_menu
+
+    end # context 'destructive methods' do
+
+  end # describe Win::Gui::Menu, ' defines a set of API functions related to menus'
+
+#  describe Win::Gui::Menu, ' defines convenience/service methods on top of Windows API' do
+#  end # Win::Gui::Menu, ' defines convenience/service methods on top of Windows API'
+end