Developers Howto

Contents 1 How to get tracks for a given author, album, year or style ? 2 How to get playable files for any item (logical or physical)? 3 How to filter a list of items ? 4 How to get the number of items (track, files...) ? 5 How to add a new option ? 6 How are managed window startup sizes and positions ? 7 How to manage right clicks ? 8 How to use the font manager ? 9 How to format dates ? 10 How to get good random value ?

How to get tracks for a given author, album, year or style ?

Use:

TrackManager.getAssociatedTracks()

How to get playable files for any item (logical or physical)?

• Use methods

Util.getPlayableFiles()

How to filter a list of items ?

• Use method

Filter.filterItems(<list>,<property name>,<value>)

How to get the number of items (track, files...) ?

• Use this method from ItemManager? public int getElementCount()
• Exemple : to get number of tracks in the collection, use:

TrackManager.getInstance.getElementCount()

How to add a new option ?

• Add the option name in org.jajuk.util.ITechnicalStrings :

public static final String CONF_AUDIOSCROBBLER_ENABLE = "jajuk.network.audioscrobbler"; 

• Always set the default value in org.jajuk.util.ConfigurationManager :

properties.put(CONF_AUDIOSCROBBLER_ENABLE, FALSE);

• Use setProperty() method to set it in the program and getBoolean, getProperty(), getInt()... methods to retrieve it. Options are automatically saved to the conf.properties file at shutdown and loaded at startup.

How are managed window startup sizes and positions ?

• Default size is set using this algorithm:

begin
 width = screen width
 if width > 1400  
   width = 1200  //deal with dual heads
 else
   width = screen width - 120
 height = screen height
 if height > 1200  
  height = 1000  //deal with dual heads
 else
  height = screen height - 120
end

• Then size is set at each startup using:

begin
 if we find a forced position in conf.properties (jajuk.frame.forced_position entry)
  use this position/size (used to allow XGL users to force a position)
 else
  if window manager buggy
    Apply (60,60,screen width - 120, screen height - 120)
  else 
    if stored position (jajuk.window_position) contains "max" (maximalize)
      if window manager supports expand
      	expand (the window manager then deal with task bars)
      else
   	Apply (60,60,screen width - 120, screen height - 120)
    else
     int x = configurated x
     int y = configurated y
     int width = configurated width
     int height = configurated height
     if x < 0 or x > screen width
      x = 60
     if y < 0 or y > screen height
      y = 60
     if width <= 0 or width > screen width
      width = window width - 120
     if height <= 0 or height > screen height 
      height = screen height - 120
     Apply (x,y,width,height)
end

How to manage right clicks ?

• MouseListener or MouseAdapter implementations have to follow this scheme:

public void mouseClicked(MouseEvent e) {
	//No (if MouseAdapter) or void (if MouseListener) mouseClicked() method 
 }

 public void mousePressed(MouseEvent e) {
	if (e.isPopupTrigger()) {
		//Popup management
		handlePopup(e);
	} else if ((e.getModifiersEx() & MouseEvent.CTRL_DOWN_MASK) == 0) {
		//Action click handle
		//... code
	}
 }

 public void mouseReleased(MouseEvent e) {
	if (e.isPopupTrigger()) {
		handlePopup(e);
	}
 }

• Why do we have to do this way ?
  • We don't use mouseClicked() method as the event can be thrown or not among different OS, specifications are not clear. It can be thrown in addition with mousePressed and mouseReleased events, so just don't use it.
  • So we only use mousePressed() and mouseReleased() methods. Popup display cannot be simply handled by a right click (Windows, Linux) as it can be thrown by others interractions like CTRL + click under OS X with a classic one touch mouse, so we use the isPopupTrigger() method to recognize such event. We have to check mousePressed and mouseReleased() methods as the popup request is recognized on the pressed event under most OS and on the release event under Mac OS.
  • We have to check if CTRL key is used in the mousePressed method to avoid Mac OS to execute action (ie left click event) on the press and then to display the popup on the mouseReleased() method.

• Note that what makes all this so complexe is the fact that most items can throw at the same time popup on right click and realize an action when the left click is recognized.

How to use the font manager ?

• Please always use the DownloadManager class to deal with fonts for code mutualization and performance
• If you don't find a required font in JajukFont enum, please create a new one (set its properties in the registerFonts() method)
• Fonts are accessed using  :

FontManager.getInstance().getFont(<a JajukFont>)

How to format dates ?

• Use Util.getLocaleDateFormatter() and Util.getAdditionDateFormatter() date formatters. The first method return the default date formatter for the current user and is intended for human display purpose. The second is used to store dates to be stored, it is the format used to store the date when tracks have been discovered (YYYYMMDD format)

How to get good random value ?

• Use only this method to get random value :

UtilSystem.getRandom()