de.frame4j.graf

Interface GrafHelper

All Superinterfaces:

ColorHelper, ColorVal

@MinDoc(copyright="Copyright 2000 - 2005, 2009  A. Weinert",
        author="Albrecht Weinert",
        version="V.44",
        lastModified="6.05.2021",
        purpose="graphical helpers and factories")
public interface GrafHelper
extends ColorHelper, ColorVal

Graphical helper methods.

This abstract class contains some helper methods for graphical applications for:

• colour choice,
• factories for buttons (awt.Button),
• factory methods for menu bars (awt.MenuBar, swing.JMenuBar) as well as
• handling, i.e. setting, finding and removing, listeners for menu elements,
• XML encoder and decoder for menu bars,
• a simple, universal description of Menu/JMenuBar in XML,
• surrounding of pictures.

© Copyright 2000 - 2003, 2005 Albrecht Weinert

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	GrafHelper.MBarFactory The menu bar factory.

Nested classes/interfaces inherited from interface de.frame4j.graf.ColorHelper

ColorHelper.Impl

Field Summary

Fields

Modifier and Type	Field and Description
static Action.Filter	colourChooseFilter A filter for Actions by code.
static String	DEF_DIAG_FONT_DES Default dialogue font description.
static CleverSSS	rkColIs The subsequence "color=" for white space and case ignoring search.

Fields inherited from interface de.frame4j.graf.ColorHelper

colourCmap

Fields inherited from interface de.frame4j.graf.ColorVal

bk, bl, COLOR_CHOOSE, dbl, dge, dgn, dgr, drt, dsi, dye, ge, gn, gr, hbl, hgr, hrd, hrt, nbl, or, pi, rd, rt, si, sw, ws, wt, ye

Method Summary

Modifier and Type	Method and Description
static CheckboxMenuItem	byAction(MenuComponent menuComp, String actionCommand) Determine the CheckboxMenuItem to an action command.
static JCheckBoxMenuItem	byAction(MenuElement menuComp, String actionCommand) Determine the JCheckboxMenuItem to an action command.
static JMenuItem	byAction(MenuElement menuComp, String actionCommand, boolean check) Determine the JMenuItem to an action command.
static MenuItem	byAction(Object menuComp, String actionCommand, boolean check) Determine the MenuItems to an action command.
static Color	calcFgColor(Color bg) Determine a foreground colour for a given background colour.
static boolean	fillRect(Graphics g, Color c, Image i, int x, int y, int w, int h) Filling a rectangle.
static int	getButtonNo() (Serial) number of last made button.
static Color	getColor(CharSequence colourDef) Determine a colour by a character sequence.
static Font	getFont(CharSequence fontDef) Fetch a character set (font) by a character sequence.
static Font	getFont(CharSequence name, int style, int size) Fetch a character set (font) by name and attributes.
static void	initMenu(JMenu m, ActionListener aL, ItemListener iL) Setting the listeners of a (J)Menu.
static void	initMenu(Menu m, ActionListener aL, ItemListener iL) Setting the listeners of a Menu.
static void	initMenuBar(MenuContainer mb, ActionListener aL, ItemListener iL) Setting the listeners of a MenuBar.
static Button	makeButton(String text, Font font, String command, Color bgColor, Color fgColor, ActionListener al) Making a button (Button).
static JButton	makeJButton(String text, Font font, Color bgColor, Color fgColor, Border bo) Making a button (JButton).
static JButton	makeJButton(String text, Font font, String command, Color bgColor, Color fgColor, ActionListener al, Border bo) Making a button (JButton).
static IntPairFix	paintString(Graphics g, ConstIntPair p, ConstIntPair d, String text, Color fgColor, Font font) Centred painting of a text in (p, d).
static IntPairFix	paintString(Graphics g, int x, int y, int width, int height, String text, Color fgColor, Font font) Centred painting of a text in (x,y), (width,height)).
static void	removeListenersMenu(JMenu m) Removing all listeners of a (J)Menu.
static void	removeListenersMenu(Menu m) Removing all listeners of a Menu.
static void	removeListenersMenuBar(MenuContainer mb) Removing all listeners from a MenuBar.
static BufferedImage	scaleImage(Image img, Color bgColor, int newWidth, int newHeight) Scaling a picture.
static void	setBgColor(Component c, Color bg) Set a component's foreground and background colours.
static BufferedImage	surrondImage(Image img, Color bgColor, int upM, int loM, int leM, int riM) Surround a picture.
static boolean	xmlEncode(MenuContainer mb, OutputStream out) XML coding a menu bar (MenuBar).

Field Detail

rkColIs

static final CleverSSS rkColIs

The subsequence "color=" for white space and case ignoring search.

colourChooseFilter

static final Action.Filter colourChooseFilter

A filter for Actions by code.

This filter accepts all s non null action with code "choose colour".

See Also:

Action, Action.SCOLOR

DEF_DIAG_FONT_DES

static final String DEF_DIAG_FONT_DES

Default dialogue font description.

Value: Dialog-plain-12

See Also:

Constant Field Values

Method Detail

getButtonNo

static int getButtonNo()

(Serial) number of last made button.


Every button made by makeButton() and by makeJButton() will be numbered.

makeButton

static Button makeButton(String text,
                         Font font,
                         String command,
                         Color bgColor,
                         Color fgColor,
                         ActionListener al)

Making a button (Button).

This method delivers a ready made and initialised button (awt.Button) with text, command, colours and ActionListener.
Is text null "Button56" (serial number) will be used.
Is font null, the Button class takes the parent container's font setting.
Is command null, the text will be used (which is usually a mistake in (inter) nationalisable applications).

Parameters:

text - the button's labelling. Should be changed by (inter) nationalising.

font - for labelling

command - the action command initiated by this button. Often chosen equal or similar to the labelling. Must keep its value even under (inter) nationalising.

bgColor - background colour

fgColor - text colour

al - the ActionListener (the object obeying to or forwarding the action command)

makeJButton

static JButton makeJButton(String text,
                           Font font,
                           String command,
                           Color bgColor,
                           Color fgColor,
                           ActionListener al,
                           Border bo)

Making a button (JButton).

This method delivers a ready made and initialised button swing.JButton) with text, command, colours and ActionListener.

Except for swing.JButton JButton's extra possibility to define margins via Border objects this method is equivalent to (see there) makeButton().

If a Border object bo is given, it will (of course) be used. Is bo null and bgColor not null, a (Line-) Border object in bgColor will be fetched and set. This makes the JButton rimless. In many respects is a "rimless" JButton a better substitute for a JLabel; see also makeJButton(String, Font, Color, Color, Border).

If text is longer than 3 and does not yet start by <html> (match case insensitive) and does contain <, > or &, <html> will be put in front. (JButtons, friendly, allow text formatting by HTML tags.)

An action command independent from the label gets more important in the light of those HTML-features, not to say indispensable.

See Also:

makeButton(String, Font, String, Color, Color, ActionListener), makeJButton(String, Font, Color, Color, Border)

makeJButton

static JButton makeJButton(String text,
                           Font font,
                           Color bgColor,
                           Color fgColor,
                           Border bo)

Making a button (JButton).

This method delivers a ready made and initialised button swing.JButton) with text, colour and so on but with no command nor ActionListener.

It's the simple variant of makeJButton(String, Font, String, Color, Color, ActionListener, Border) when generating (pseudo) labels.

fillRect

static boolean fillRect(Graphics g,
                        Color c,
                        Image i,
                        int x,
                        int y,
                        int w,
                        int h)

Filling a rectangle.

This method fills a rectangle with a colour, a picture or a picture + background colour, depending on what parameter is not null.

If g is null or w or h are 0, nothing happens (except return false).
If c and i are both null, nothing happens, too.

Is c given the rectangle will be filled by it.
Is i given, the picture will be scaled to rectangle and painted on it. A given c will shine through transparent areas of i.

If something is painted true respectively the result of g.drawImage(i,...) will be returned.

Parameters:

g - graphical context

c - (background) colour

i - picture

x - starting point (upper left)

y - starting point (upper left)

w - width

h - height

Returns:

true: something painted

paintString

static IntPairFix paintString(Graphics g,
                              ConstIntPair p,
                              ConstIntPair d,
                              String text,
                              Color fgColor,
                              Font font)

Centred painting of a text in (p, d).

If g is null, nothing happens.
Otherwise this method sets foreground colour and font if those parameters are not null.
If p, d or text are null (or empty) nothing else happens; the same is true for a d smaller than 6 * 6.

The FontMetrics (dependent from font and text) are determined (a quite expensive procedure) and the starting positions relative to p for centred text output are calculated. This position is also the return value.

Afterwards the text is painted centred in the rectangle d (starting at p).

If the same text has to be painted with the same font within a rectangle of the same size the returned p can (and should) be reused.

paintString

static IntPairFix paintString(Graphics g,
                              int x,
                              int y,
                              int width,
                              int height,
                              String text,
                              Color fgColor,
                              Font font)

Centred painting of a text in (x,y), (width,height)).

This is the (real) implementation of paintString(Graphics g, ConstIntPair p, ConstIntPair d, String text, Color fG, Font f) just getting (x, y) from p and (width, height) from d.

Notwithstanding the not recommendable signature (8 parameters) this method may very well be used directly.

calcFgColor

static Color calcFgColor(Color bg)

Determine a foreground colour for a given background colour.

The colour returned to the given (background) colour bg is either white ColorVal.ws) or black (ColorVal.sw), depending on the (weighted) brightness of bg.
Algorithm: From bg's RGB values a gray value will be calculated, using ITU standard weights (222, 707, 71; according to recommendation 709, D65). About 51% will be used as threshold.

Specified by:

calcFgColor in interface ColorHelper

Parameters:

bg - the background colour (null returns black)

Returns:

a fitting / contrasting foreground either white or black

setBgColor

static void setBgColor(Component c,
                       Color bg)

Set a component's foreground and background colours.

The background colour of c will be set by bg.
The foreground colour will be set as white or black, whatever gives a good contrast to bg.

Specified by:

setBgColor in interface ColorHelper

See Also:

calcFgColor(Color)

getColor

static Color getColor(CharSequence colourDef)

Determine a colour by a character sequence.

The character sequence colourDef is stripped from surrounding whitespace and quotes. If null or empty null is returned.

If the subsequence "color=" is found (ignoring white spaces) within colourDef only the token following the = is considered.

The sequence colourDef or its remaining token is interpreted decimal, octal or hexadecimal as 24 bit number to define a colour as RGB (0xrrggbb); see also Color.decode(String). A leading sharp (#) will be replaced before by 0x (#FFC0C0 -> 0xffcoco) to accept HTML colour values, too.

The second possible interpretation of colourDef is as an English, German or French colour name or industry standard abbreviation.

As an example, the following sequences (among others) will be understood as pure blue:

• 255
• "255"
• 0x0000ff
• blue
• blau
• bleu
• bl
• bcColor="blue" align="center"

See the hints at GrafVal.COLOR_CHOOSE.

If all (those toils of) interpretation fail, null is returned.

The lower cased token part of colourDef is used as key to a cache used and filled by this method. This partly avoids double decoding and generating.

Specified by:

getColor in interface ColorHelper

Parameters:

colourDef - the colour definition

Returns:

Color fitting colourDef or null

See Also:

ColorVal.COLOR_CHOOSE, Action

getFont

static Font getFont(CharSequence name,
                    int style,
                    int size)

Fetch a character set (font) by name and attributes.

The character sequence fontDef is stripped from surrounding whitespace. If (then) empty or null, null is returned. The same happens if size is outside 4..200.

Otherwise an according Font is returned from a cache or constructed.

Besides the checking and caching this method is mostly equivalent to Font.Font(name, style, size).

Parameters:

name - a font's name (not empty after stripping surrounding white space)

style - the Font's style value (Font class constants ORed)

size - the Font's the point size (4..200)

Returns:

the according font or null if parameter conditions violated

See Also:

getFont(CharSequence)

getFont

static Font getFont(CharSequence fontDef)

Fetch a character set (font) by a character sequence.

The character sequence fontDef is stripped from surrounding whitespace. If empty it is substituted by DEF_DIAG_FONT_DES. The resulting sequence is used for getting a Font as returned by Font.decode().

This method either gets this font from a cache or uses Font.decode() to get (and cache) it.

Parameters:

fontDef - Font definition (face-style-size)

Returns:

an according font

See Also:

getFont(CharSequence, int, int)

xmlEncode

static boolean xmlEncode(MenuContainer mb,
                         OutputStream out)

XML coding a menu bar (MenuBar).

The awt.MenuBar given as parameter mb or any other awt.MenuMenuContainer or swing.JMenuBar will be XML encoded including all its contained Menus and MenuItems respectively JMenus and JMenuItems.

In case of success true is returned. The OutputStream out is closed afterwards.

See Also:

MLHelper.xmlEncode(Object, String)

initMenuBar

static void initMenuBar(MenuContainer mb,
                        ActionListener aL,
                        ItemListener iL)

Setting the listeners of a MenuBar.

For all Menus of (J)MenuBar mb all (J)MenuItems will get the ActionListener aL and all (J)CheckboxMenuItems will get the ItemListener iL if they have no such listener yet (using the method initMenu()).

Parameters:

mb - MenuBar, may be a awt.MenuBar or a swing.JMenuBar sein

initMenu

static void initMenu(Menu m,
                     ActionListener aL,
                     ItemListener iL)

Setting the listeners of a Menu.

For the Menu m all MenuItems get the ActionListener aL.
If iL is not null all CheckboxMenuItems get the ItemListener iL (instead of aL).
This only happens for those MenuItems having no such listener yet.
Sub menus are visited recursively.

initMenu

static void initMenu(JMenu m,
                     ActionListener aL,
                     ItemListener iL)

Setting the listeners of a (J)Menu.

For the JMenu m all JMenuItems get the ActionListener aL.
If iL is not null all CheckboxMenuItems get the ItemListener iL (instead of aL).
This only happens for those MenuItems having no such listener yet.
Sub menus are visited recursively.

removeListenersMenuBar

static void removeListenersMenuBar(MenuContainer mb)

Removing all listeners from a MenuBar.

In Menus of the MenuBar mb the menu items will be freed from the listeners (ActionListener or ItemListener) using the (fitting overloaded) method removeListenersMenu().

Parameters:

mb - MenuBar, may be a awt.MenuBar or a swing.JMenuBar

removeListenersMenu

static void removeListenersMenu(JMenu m)

Removing all listeners of a (J)Menu.

In the JMenu m from all JMenuItems the ActionListeners are removed and from all JCheckboxMenuItems the ItemListeners.
Sub menus are visited recursively.

removeListenersMenu

static void removeListenersMenu(Menu m)

Removing all listeners of a Menu.

In the Menu m from all MenuItems the ActionListeners are removed and from all CheckboxMenuItems the ItemListeners.
Sub menus are visited recursively.

byAction

static MenuItem byAction(Object menuComp,
                         String actionCommand,
                         boolean check)

Determine the MenuItems to an action command.

This method designates a MenuItem represented by or contained in menuComp. Container like MenuBars or Menus are searched recursively.

The search ends at the first CheckboxMenuItem and if check is false also MenuItem, having actionCommand set as action command.

If no fitting item is found null is returned.

Due to the recursive search the method may be a bit expensive. After generating menuComp the result for every interesting action command should be determined once and stored.

Parameters:

menuComp - the containing menu component
(usually a MenuBar or a Menu)

actionCommand - the search criterion action command

check - true: consider only CheckboxMenuItems
false: consider all MenuItems

Returns:

fitting [Checkbox-]MenuItem or null

byAction

static CheckboxMenuItem byAction(MenuComponent menuComp,
                                 String actionCommand)

Determine the CheckboxMenuItem to an action command.

The call is equivalent to:

  (CheckBoxMenuItem)byAction(menuComp, actionCommand, true)

Only for better readability.

Parameters:

menuComp - the containing menu component
(usually a MenuBar or a Menu)

actionCommand - the search criterion action command

Returns:

fitting CheckboxMenuItem or null

byAction

static JMenuItem byAction(MenuElement menuComp,
                          String actionCommand,
                          boolean check)

Determine the JMenuItem to an action command.

This method designates a JMenuItem represented by or contained in menuComp. Container like JMenuBars or JMenus are searched recursively.

The search ends at the first JCheckboxMenuItem and if check is false also JMenuItem, having actionCommand set as action command.

If no fitting item is found null is returned.

Due to the recursive search the method may be a bit expensive. After generating menuComp the result for every interesting action command should be determined once and stored.

Parameters:

menuComp - the containing JMenu component
(usually a JMenuBar or a JMenu)

actionCommand - the search criterion action command

check - true: consider only JCheckboxMenuItems
false: consider all JMenuItems

Returns:

fitting J[Checkbox-]MenuItem or null

byAction

static JCheckBoxMenuItem byAction(MenuElement menuComp,
                                  String actionCommand)

Determine the JCheckboxMenuItem to an action command.

The call is equivalent to:

  (CheckBoxMenuItem)byAction(menuComp, actionCommand, true)

Parameters:

menuComp - the containing JMenu component
(usually a JMenuBar or a JMenu)

actionCommand - the search criterion action command

Returns:

fitting JCheckboxMenuItem or null

surrondImage

static BufferedImage surrondImage(Image img,
                                  Color bgColor,
                                  int upM,
                                  int loM,
                                  int leM,
                                  int riM)

Surround a picture.

The given picture img ( 3 * 8 bit colour model) will be enlarged by the given margins (the result being returned as new image).

Is img null or of zero or unknown size, null will be returned.

If (just) one margin is outside the range 0 to 400, all (!) margins are set to 0.

Specified by:

surrondImage in interface ColorHelper

Parameters:

img - the picture to be surrounded

bgColor - background respectively margin colour (default ColorVal.ws).

upM - upper margin in pixel (0..400).

loM - leM - riM - ditto lower, left and right.

Returns:

the picture as buffered image and (if given in range) surrounded / enlarged by margins

scaleImage

static BufferedImage scaleImage(Image img,
                                Color bgColor,
                                int newWidth,
                                int newHeight)

Scaling a picture.

The given picture img ( 3 * 8 bit colour model) will be stretched or shrunk to the given size and returned as BufferedImage.

Is img null or of zero or unknown size, null or is the one of the wanted sizes less than 1, null will be returned.

Are the given and ordered dimensions the same and is img of type BufferedImage, img itself will be returned (not copied).

Specified by:

scaleImage in interface ColorHelper

Parameters:

img - the picture to scale

bgColor - background colour (used to prefill the new buffered image, if not null)

newHeight - new height

newWidth - new width

Returns:

the scaled picture as buffered image