Extended maintenance of Ruby 1.9.3 ended on February 23, 2015. Read more

In Files

  • win32ole/win32ole.c

WIN32OLE_EVENT

WIN32OLE_EVENT objects controls OLE event.

Public Class Methods

message_loop click to toggle source

Translates and dispatches Windows message.

 
               static VALUE
fev_s_msg_loop(VALUE klass)
{
    ole_msg_loop();
    return Qnil;
}
            
new(ole, event) #=> WIN32OLE_EVENT object. click to toggle source

Returns OLE event object. The first argument specifies WIN32OLE object. The second argument specifies OLE event name.

ie = WIN32OLE.new('InternetExplorer.Application')
ev = WIN32OLE_EVENT.new(ie, 'DWebBrowserEvents')
 
               static VALUE
fev_initialize(int argc, VALUE *argv, VALUE self)
{
    ev_advise(argc, argv, self);
    evs_push(self);
    rb_ivar_set(self, id_events, rb_ary_new());
    fev_set_handler(self, Qnil);
    return self;
}
            

Public Instance Methods

WIN32OLE_EVENT#handler click to toggle source

returns handler object.

 
               static VALUE
fev_get_handler(VALUE self)
{
    return rb_ivar_get(self, rb_intern("handler"));
}
            
WIN32OLE_EVENT#handler= click to toggle source

sets event handler object. If handler object has onXXX method according to XXX event, then onXXX method is called when XXX event occurs.

If handler object has method_missing and there is no method according to the event, then method_missing called and 1-st argument is event name.

If handler object has onXXX method and there is block defined by #on_event(‘XXX’){}, then block is executed but handler object method is not called when XXX event occurs.

class Handler
  def onStatusTextChange(text)
    puts "StatusTextChanged"
  end
  def onPropertyChange(prop)
    puts "PropertyChanged"
  end
  def method_missing(ev, *arg)
    puts "other event #{ev}"
  end
end

handler = Handler.new
ie = WIN32OLE.new('InternetExplorer.Application')
ev = WIN32OLE_EVENT.new(ie)
ev.on_event("StatusTextChange") {|*args|
  puts "this block executed."
  puts "handler.onStatusTextChange method is not called."
}
ev.handler = handler
 
               static VALUE
fev_set_handler(VALUE self, VALUE val)
{
    return rb_ivar_set(self, rb_intern("handler"), val);
}
            
WIN32OLE_EVENT#off_event([event]) click to toggle source

removes the callback of event.

ie = WIN32OLE.new('InternetExplorer.Application')
ev = WIN32OLE_EVENT.new(ie)
ev.on_event('BeforeNavigate2') {|*args|
  args.last[6] = true
}
  ...
ev.off_event('BeforeNavigate2')
  ...
 
               static VALUE
fev_off_event(int argc, VALUE *argv, VALUE self)
{
    VALUE event = Qnil;
    VALUE events;

    rb_secure(4);
    rb_scan_args(argc, argv, "01", &event);
    if(!NIL_P(event)) {
        if(TYPE(event) != T_STRING && TYPE(event) != T_SYMBOL) {
            rb_raise(rb_eTypeError, "wrong argument type (expected String or Symbol)");
        }
        if (TYPE(event) == T_SYMBOL) {
            event = rb_sym_to_s(event);
        }
    }
    events = rb_ivar_get(self, id_events);
    if (NIL_P(events)) {
        return Qnil;
    }
    ole_delete_event(events, event);
    return Qnil;
}
            
WIN32OLE_EVENT#on_event([event]){...} click to toggle source

Defines the callback event. If argument is omitted, this method defines the callback of all events. If you want to modify reference argument in callback, return hash in callback. If you want to return value to OLE server as result of callback use `return’ or :return.

ie = WIN32OLE.new('InternetExplorer.Application')
ev = WIN32OLE_EVENT.new(ie)
ev.on_event("NavigateComplete") {|url| puts url}
ev.on_event() {|ev, *args| puts "#{ev} fired"}

ev.on_event("BeforeNavigate2") {|*args|
  ...
  # set true to BeforeNavigate reference argument `Cancel'.
  # Cancel is 7-th argument of BeforeNavigate,
  # so you can use 6 as key of hash instead of 'Cancel'.
  # The argument is counted from 0.
  # The hash key of 0 means first argument.)
  {:Cancel => true}  # or {'Cancel' => true} or {6 => true}
}

ev.on_event(...) {|*args|
  {:return => 1, :xxx => yyy}
}
 
               static VALUE
fev_on_event(int argc, VALUE *argv, VALUE self)
{
    return ev_on_event(argc, argv, self, Qfalse);
}
            
WIN32OLE_EVENT#on_event_with_outargs([event]){...} click to toggle source

Defines the callback of event. If you want modify argument in callback, you could use this method instead of #on_event.

ie = WIN32OLE.new('InternetExplorer.Application')
ev = WIN32OLE_EVENT.new(ie)
ev.on_event_with_outargs('BeforeNavigate2') {|*args|
  args.last[6] = true
}
 
               static VALUE
fev_on_event_with_outargs(int argc, VALUE *argv, VALUE self)
{
    return ev_on_event(argc, argv, self, Qtrue);
}
            
WIN32OLE_EVENT#unadvise → nil click to toggle source

disconnects OLE server. If this method called, then the WIN32OLE_EVENT object does not receive the OLE server event any more. This method is trial implementation.

ie = WIN32OLE.new('InternetExplorer.Application')
ev = WIN32OLE_EVENT.new(ie)
ev.on_event() {...}
   ...
ev.unadvise
 
               static VALUE
fev_unadvise(VALUE self)
{
    struct oleeventdata *poleev;
    Data_Get_Struct(self, struct oleeventdata, poleev);
    if (poleev->pConnectionPoint) {
        ole_msg_loop();
        evs_delete(poleev->event_id);
        poleev->pConnectionPoint->lpVtbl->Unadvise(poleev->pConnectionPoint, poleev->dwCookie);
        OLE_RELEASE(poleev->pConnectionPoint);
        poleev->pConnectionPoint = NULL;
    }
    return Qnil;
}
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.