Class: Umbra::Widget

Inherits:
Object
  • Object
show all
Includes:
EventHandler, KeyMappingHandler
Defined in:
lib/umbra/widget.rb

Overview

Parent class of all widgets/controls that are displayed on the screen/window and are managed by Form. Many attributes use ‘attr_property` instead of `attr_accessor`. This is used for elements that must repaint the widget whenever updated. They also fire a property change event. These properties may not show up in the generated RDoc. This class will not be instantiated by programs, only its subclasses will be. Widget registers `:ENTER` `:LEAVE` `:CHANGED` and `:PROPERTY_CHANGE` events. Widget defines three states: `:NORMAL` `:HIGHLIGHTED` and `:SELECTED`.

`HIGHLIGHTED` refers to the single widget that is focussed. 
`SELECTED` is only for Togglebuttons that may be in `SELECTED` state.
`NORMAL` state is for all others (the default state).

Direct Known Subclasses

Box, Button, Field, Label, Multiline

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from KeyMappingHandler

#_process_key, #bind_key, #bind_keys, #process_key, #unbind_key

Methods included from EventHandler

#bind_event, #event?, #fire_handler, #fire_property_change, #register_events

Constructor Details

#initialize(aconfig = {}) {|Widget| ... } ⇒ Widget

Returns a new instance of Widget.

Parameters:

  • aconfig (Hash) (defaults to: {}) —

    initialization parameters such as row, col, height, width, color_pair, text.

Yields:



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/umbra/widget.rb', line 114

def initialize aconfig={}, &block
  @row_offset ||= 0
  @col_offset ||= 0
  @state = :NORMAL

  @handler = nil # we can avoid firing if nil
  # These are standard events for most widgets which will be fired by 
  # Form. In the case of CHANGED, form fires if it's editable property is set, so
  # it does not apply to all widgets.
  register_events( [:ENTER, :LEAVE, :CHANGED, :PROPERTY_CHANGE])
  @repaint_required = true

  aconfig.each_pair { |k,v| variable_set(k,v) }
  #instance_eval &block if block_given?
  if block_given?
    if block.arity > 0
      yield self
    else
      self.instance_eval(&block)
    end
  end
end

Instance Attribute Details

#col ⇒ Object

location of object (column)



77
78
79
 
# File 'lib/umbra/widget.rb', line 77

def col
  @col
end

#col_offset ⇒ Object (readonly)

where should the cursor be placed to start with



91
92
93
 
# File 'lib/umbra/widget.rb', line 91

def col_offset
  @col_offset
end

#curpos ⇒ Object

cursor position inside object - column, not row.



86
87
88
 
# File 'lib/umbra/widget.rb', line 86

def curpos
  @curpos
end

#focusable ⇒ Object

boolean can this get focus or not.



96
97
98
 
# File 'lib/umbra/widget.rb', line 96

def focusable
  @focusable
end

#graphic ⇒ Object

window which should be set by form when adding



89
90
91
 
# File 'lib/umbra/widget.rb', line 89

def graphic
  @graphic
end

#handler ⇒ Hash (readonly)

Returns event handler hash containing key and block association.

Returns:

  • (Hash) —

    event handler hash containing key and block association



107
108
109
 
# File 'lib/umbra/widget.rb', line 107

def handler
  @handler
end

#key_label ⇒ String (readonly)

Returns descriptions for each key set in _key_map, NOT YET displayed TODO.

Returns:

  • (String) —

    descriptions for each key set in _key_map, NOT YET displayed TODO



104
105
106
 
# File 'lib/umbra/widget.rb', line 104

def key_label
  @key_label
end

#modified ⇒ Object

boolean, value modified or not



98
99
100
 
# File 'lib/umbra/widget.rb', line 98

def modified
  @modified
end

#name ⇒ Object

documentation, used in print statements



85
86
87
 
# File 'lib/umbra/widget.rb', line 85

def name
  @name
end

#repaint_required ⇒ Object

Parameters:

  • repaint_required (true, false) —

    is a repaint required or not, boolean



110
111
112
 
# File 'lib/umbra/widget.rb', line 110

def repaint_required
  @repaint_required
end

#row ⇒ Integer?

get row of widget

Returns:

  • (Integer, nil) —

    row of widget



302
303
304
305
306
307
308
 
# File 'lib/umbra/widget.rb', line 302

def row
  return nil unless @row
  if @row < 0
    return FFI::NCurses.LINES + @row
  end
  @row
end

#row_offset ⇒ Object (readonly)

where should the cursor be placed to start with



91
92
93
 
# File 'lib/umbra/widget.rb', line 91

def row_offset
  @row_offset
end

#state ⇒ Object

:NORMAL, :SELECTED, :HIGHLIGHTED



90
91
92
 
# File 'lib/umbra/widget.rb', line 90

def state
  @state
end

Instance Method Details

#_form=(aform) ⇒ Object

:nodoc:



267
268
269
 
# File 'lib/umbra/widget.rb', line 267

def _form=(aform)    #:nodoc:
  @_form = aform
end

#color_pair ⇒ Object

Parameters:

  • color_pair (Integer) —

    color pair of widget (when not focussed)



81
 
# File 'lib/umbra/widget.rb', line 81

attr_property  :color_pair

#command(*args, &block) ⇒ Object

A general method for all widgets to override with their favorite or most meaninful event This is a convenience method. Widgets that have a ‘PRESS` event will bind the given block to PRESS, all others to the `CHANGED` event.



259
260
261
262
263
264
265
 
# File 'lib/umbra/widget.rb', line 259

def command *args, &block
  if event? :PRESS
    bind_event :PRESS, *args, &block
  else
    bind_event :CHANGED, *args, &block
  end
end

#getvalue ⇒ String

Returns the value of the widget.

Returns:

  • (String) —

    the value of the widget.



186
187
188
 
# File 'lib/umbra/widget.rb', line 186

def getvalue
  @text
end

#getvalue_for_paint ⇒ String

Am making a separate method since often value for print differs from actual value

Returns:

  • (String) —

    the value of the widget for painting.



193
194
195
 
# File 'lib/umbra/widget.rb', line 193

def getvalue_for_paint
  getvalue
end

#handle_key(ch) ⇒ 0, :UNHANDLED

Handle keys entered by user when this widget is focussed. Executes blocks bound to given key or else returns control to Form. To be called at end of ‘handle_key` of widgets so installed actions can be executed.

Parameters:

  • ch (Integer) —

    keystroke entered

Returns:

  • (0, :UNHANDLED) —

    return value of block executed for given keystroke



234
235
236
237
238
 
# File 'lib/umbra/widget.rb', line 234

def handle_key(ch)
  ret = process_key ch, self
  return :UNHANDLED if ret == :UNHANDLED
  0
end

#height ⇒ Integer?

Get height of widget. Used only for Multline widgets

Returns:

  • (Integer, nil) —

    height of widget if applicable



291
292
293
294
295
296
297
298
 
# File 'lib/umbra/widget.rb', line 291

def height
  return nil unless @height
  if @height < 0
    return ((FFI::NCurses.LINES + @height) - self.row) + 1
    #return (FFI::NCurses.LINES + @height) 
  end
  @height
end

#highlight_attr ⇒ Object

Parameters:

  • highlight_attr (Integer) —

    visual attribute of widget when focussed



75
 
# File 'lib/umbra/widget.rb', line 75

attr_property :highlight_attr

#init_vars ⇒ Object

Initialise internal variables



142
143
144
145
 
# File 'lib/umbra/widget.rb', line 142

def init_vars  #:nodoc:
  # just in case anyone does a super. Not putting anything here
  # since i don't want anyone accidentally overriding
end

#modified? ⇒ true, false

Widget modified or not. typically will be overridden to check if value changed from what it was on enter.

Returns:

  • (true, false) —

    modified since on_enter or not



150
151
152
 
# File 'lib/umbra/widget.rb', line 150

def modified?
  @modified
end

#on_enter ⇒ Object

triggered whenever a widget is entered. Will invoke ‘:ENTER` handler/event



156
157
158
159
160
161
162
163
 
# File 'lib/umbra/widget.rb', line 156

def on_enter
  ## Form has already set this, and set modified to false
  @state = :HIGHLIGHTED    # duplicating since often these are inside containers
  #@focussed = true
  if @handler && @handler.has_key?(:ENTER)
    fire_handler :ENTER, self
  end
end

#on_leave ⇒ Object

Called when user exits a widget Will invoke ‘:LEAVE` handler/event



167
168
169
170
171
172
173
 
# File 'lib/umbra/widget.rb', line 167

def on_leave
  @state = :NORMAL    # duplicating since often these are inside containers
  #@focussed = false
  if @handler && @handler.has_key?(:LEAVE)
    fire_handler :LEAVE, self
  end
end

#repaint ⇒ Object

Default repaint method. Called by form for all widgets. widget does not have display_length. This should be overriden by concrete subclasses.



200
201
202
203
204
205
206
207
 
# File 'lib/umbra/widget.rb', line 200

def repaint
  r,c = rowcol
  $log.debug("widget repaint : r:#{r} c:#{c} col:#{@color_pair}" )
  value = getvalue_for_paint
  len = self.width || value.length
  acolor = @color_pair 
  @graphic.printstring r, c, "%-*s" % [len, value], acolor, attr()
end

#repaint_all(tf) ⇒ Object

is the entire widget to be repainted including things like borders and titles earlier took a default of true, now must be explicit. Perhaps, not used currently.



242
243
244
245
246
247
 
# File 'lib/umbra/widget.rb', line 242

def repaint_all(tf)  #:nodoc:
  # NOTE NOT USED
  raise " not used repaint all"
  @repaint_all = tf
  @repaint_required = tf
end

#rowcol ⇒ Integer

Returns row and col is where a widget starts. offsets usually take into account borders. the offsets typically are where the cursor should be positioned inside, upon on_enter.

Returns:

  • (Integer) —

    row of widget where painting data actually starts

  • (Integer) —

    col of widget where painting data actually starts



181
182
183
 
# File 'lib/umbra/widget.rb', line 181

def rowcol
  return self.row+@row_offset, self.col+@col_offset
end

#set_form_col(col1 = @curpos) ⇒ Object

set cursor on correct column, widget Ideally, this should be overriden, as it is not likely to be correct. NOTE: this is okay for some widgets but NOT for containers that will call their own components SFR and SFC Currently, Field has overriden this. setrowcol does not exist any longer.



221
222
223
224
225
226
227
 
# File 'lib/umbra/widget.rb', line 221

def set_form_col col1=@curpos
  @curpos = col1 || 0 # 2010-01-14 21:02 
  #@form.col = @col + @col_offset + @curpos
  c = @col + @col_offset + @curpos
  #$log.warn " #{@name} empty set_form_col #{c}, curpos #{@curpos}  , #{@col} + #{@col_offset} #{@form} "
  setrowcol nil, c
end

#set_form_row ⇒ Object

:nodoc:



210
211
212
213
214
 
# File 'lib/umbra/widget.rb', line 210

def set_form_row #:nodoc:
  raise "uncalled set_form_row"
  r, c = rowcol
  setrowcol row, nil  # does not exist any longer
end

#text ⇒ Object

Parameters:

  • text (String) —

    common interface for text related to a field, label, textview, button etc



66
 
# File 'lib/umbra/widget.rb', line 66

attr_property :text

#touch ⇒ Object

Shortcut for users to indicate that a widget should be redrawn since some property has been changed. Now that I have created attr_property this may not be needed



251
252
253
 
# File 'lib/umbra/widget.rb', line 251

def touch
  @repaint_required = true
end

#variable_set(var, val) ⇒ Object

:nodoc:



137
138
139
 
# File 'lib/umbra/widget.rb', line 137

def variable_set var, val #:nodoc:
  send("#{var}=", val) 
end

#visible ⇒ Object

Parameters:

  • attr (true, false) —

    should the widget be displayed or not



94
 
# File 'lib/umbra/widget.rb', line 94

attr_property  :visible

#width ⇒ Integer?

Get width of widget, treating negatives as relative width.

Returns:

  • (Integer, nil) —

    returns width of widget



68
 
# File 'lib/umbra/widget.rb', line 68

attr_property   :width, :height