[pago]

Das PgsAction-Framework entstand als Nebenprodukt der SimpleEdit-IDE und ist auf einfache Benutzung, Erweiterbarkeit und Flexibilität optimiert.

Es erweitert die Swing Action-API um Kontext- und Statussensitivität und vereinfacht die Internationalisierung der Actions. Dabei ist es extrem klein (20kb) und einfach zu verwenden.

Kommentare sind erwünscht.

Download

[beny_mcde]

könntest du vieleicht ein kleines beispiel programm zur verfügung stellen.
habe gerade langweile (bin arbeiten) und wollte das mal ausprobieren,
aber irgendwie weiß aber irgendwie nicht so genau wo und mit was ich anfangen soll...

[pago]

Theoretisch ne tolle Idee, aber praktisch bringts nicht viel, weil man bei nem kleinen Programm den Vorteil nicht sieht.

Viele Beispiele für Verwendung des Packages findest du in SimpleEdit (org.simpleedit.action.*-Packages + org.simpleedit.MainFrame) (Quellcode findest du hier).
Mehr gibts aktuell nicht, hatte gehofft, die Doku wäre ausführlich genug.

[beny_mcde]

hm dann werd ich mich wenns ma wieder nichts zu tun gibt durch den source code des editors fummeln...

hatte mir das teil gestern schon runtergeladen aber nur n bischen mit gespielt aber nicht in den quellcode geschaut.....
hierzu muss ich sagen, sieht ja wirklich sehr nice aus. und die startup time ist beeindruckend (für ein java programm...).
ich kann mich erinnern das ding schonmal vor etwas mehr als einem halben jahr getestet zu habe, bezüglich der UI hat sich ja einiges getan.

ein tip für die batch datei, wenn du den anfang der zeil "java" in "start javaw" umänderst verschwindet das commandozeilen fenster gleich wieder.
wenn du es für debug zwecke noch haben willst kannst du "start java" verwenden so schließt sich das erste fenster gleich wieder und ein zweites öffnet sich in dem nur der java output angezeigt wird...

[pago]

Danke für den Tipp. Das ist echt hilfreich.
Gewollt war den Fenster nicht, nur ungekonnt.

Ja, die GUI hat sich erheblich verändert, ist auch ne komplett andere Basis.


Also, dass Prinzip bei PgsAction ist sehr simpel. Statt direkt AbstractAction zu erweitern, ist die Superklasse halt (meistens) AbstractSystemAction (in SimpleEdit ist es SystemAction, dass solltest du einfach ignorieren).
Hier ein Beispiel: NewFileAction.java.

Anhand des Beispiels lässt sich folgendes feststellen: Statt des "richtigen" Textes wird eine ID übergeben. Diese wird (standardmäßig) aus einem ResourceBundle mit dem Namen "Bundle" im gleichen Package, in der auch die Klasse ist, gelesen.
In dem Beispiel müsste also eigentlich eine "org/simpleedit/action/file/Bundle.properties" existieren, die den Key "file.new" hat.
Beispielwert wäre "&Neue Datei@control N". Das Zeichen direkt nach dem "&" wird als Mnemonic verwertet (das "&" wird entfernt). Das, was nach dem "@" steht, wird als Accelerator gesetzt (@see KeyStroke.getKeyStroke(String)). Ist also recht simpel alles.

Prinzip ist bei PgsAction ist es, dass die Actions tatsächlich die Controller-Rolle übernehmen. Maximalen Nutzen erreichst du also, indem du in einer Action nicht einfach ne Methode einer anderen Klasse aufrufst, sondern schon ein bisschen hirnschmalz reinsteckst. Das verlinkte Beispiel ist dahingehend noch nichtmal optimal. Besseres Beispiel dafür könnte die OpenFTPConnectionAction.java sein.

Nachdem das geklärt wurde, geht's dann weiter. Wenn du die Actions hast, brauchst du Menüs und Toolbars. Die generierst du dir in PgsAction nicht selbst, sondern du fügst sie einem ActionContainer hinzu (extends AbstractSystemAction, implements ListModel).
Das könnte so aussehen: CodeMenuAction.java (ja, es ist tatsächlich so einfach).

Dabei siehst du auch direkt eines der wichtigsten Merkmale: Actions sind Singletons (du kannst allerdings auch eine Instanz einer Action hinzufügen).

Um nun an diesen Container zu kommen würdest du sowas schreiben:

ActionContainer codeMenu = (ActionContainer)ActionManager.getDefaultInstance().get(CodeMenuAction.class);

Mit dem Teil kannst du dann arbeiten. z.B. ein Menü erzeugen:

JMenu menu = codeMenu.createMenu();

Oder du kannst eine neue Action hinzufügen:

codeMenu.add(MyAction.class);

Das besondere ist, dass jeder Komponente, die mit einer der create*-Methoden erzeugt wurde, ein neues entsprechendes Element hinzugefügt wird. Das gleiche passiert, wenn du eine Action entfernst.

Weiter im Text...
Jetzt mal ein Beispiel für eine "ContextAwareAction":

public class OpenImageAction extends AbstractSystemAction implements ContextAwareAction, ListSelectionListener {
	public OpenImageAction() {
		super("openimage");
	}

	public void actionPerformed(ActionEvent e) {
		JList list = (JList) e.getSource();
		File file = (File) list.getSelectedValue();

		try {
			SimpleDemo.getInstance().getImagePanel().setImage(file);
		} catch (MalformedURLException e1) {
			e1.printStackTrace();
		}
	}

	public void addContext(Object context, JComponent presentation) {
		JList list = (JList) context; // "presentation" is just the JButton/JMenuItem whatever that gets an instance of this action
		list.addListSelectionListener(this);
	}

	public void valueChanged(ListSelectionEvent e) {
		JList list = (JList) e.getSource();

		File file = ((File) list.getSelectedValue());
		String name = null;
		if(file != null) {
			name = file.getName();
		}
		setEnabled(name != null && (name.endsWith("jpg") || name.endsWith("gif") || name.endsWith("png")));
	}
}

getSource() liefert dabei immer den Context, in dem die Action ausgeführt wurde.
addContext() kann manuell aufgerufen werden, oder du verwendest einfach die ContextSensitive*Provider als Parameter für die create*-Methode des ActionContainers, der die Action beinhaltet und gibst ihm den entsprechenden Context mit.

*puh*

Ok, eines noch. PgsAction kann auch mit JCheckBoxMenuItem und co umgehen.
Dabei empfiehlt es sich, eine Oberklasse zu implementieren, die die entsprechende Gruppe verwaltet. Beispiel: TokenMarkerAction.java (statt SimpleAbstractStateAction würdest du allerdings AbstractStateAction schreiben).
Die tatsächliche Implementierung ist dann ein Kinderspiel: TextTokenMarkerAction.java (als Beispiel für den vorselektierten Wert).

Das ist alles, was man tun muss, um so ein Menü hinzubekommen, wie SimpleEdit es beim "Syntax"-Menü hat, und das ganze dann auch noch zu synchronisieren (SimpleEdit hat einmal das "Syntax"-Menü, es gibt aber auch noch nen entsprechenden Knopf, der das gleiche Menü anzeigt).

Ok, ich hoffe das war jetzt irgendwie hilfreich.

[beny_mcde]

ahhh... man muss den leuten nur ein bischen honig ums maul schmieren und schon bekommt man den beispielcode
mach jetzt feierabend aber werd mir das montag oder am we wenn zeit bleibt mal anschauen...

[pago]

*g*

Das vereinfacht die Mühe, die das schreiben kostet, tatsächlich erheblich.

Ich vergesse nur immer, dass andere meine APIs nicht kennen, folglich also die Beispiele nicht so einfach finden können. *g*

[beny_mcde]

soo hab mal ein paar minuten gefunden. das ganze macht einen guten eindruck... obwohl mir trotz deiner ausführlichen beschreibung nicht alles zu 100% klar geworden ist (scheint meistens so zu sein, wenn man den code nicht selber geschrieben hat)....

Ein ActionContainer erbt ja auch von der AbstractAction.
Bei einer MenuBar würde dann ja z.B. ein ActionContainer für ein Menu Stehen, die in ihm hinzugefügten Actions sind die einzelnen MenuPunkte.
Nun erwartete ich das beim öffnen des Menu's die actionPerformed methode des ActionsConteiners aufgerufen wird, was aber nicht der fall war.
Hab ich was falsch gemach oder wird die actionPerformed Methode des ActionContainers anders/garnich verwendet?

Was hat es mit den ActionGroups auf sich? Hab das nicht sinnvoll zum einsatz bringen können, aber das sollte doch irgendwie so funktionieren:
Ich habe einen ActionContainer für eine JMenuBar, ihm kann ich mehrere ActionsGroups hinzufügen welche die einzelnen Menu's repräsentieren. Der ActionGroup kann ich dann für untermenu's weitere ActionsGroups hinzufügen oder für Menupunkte AbstractSystemActions. Vieleicht hab ich das auch falsch verstanden...


Zu meckern gibts natürlich auch was, und zwar die Sprachbundels, auch wenn es der Standartweg ist finde ich es nicht gut die Bundels im dazugehörigen package aufzubewahren. Bei einem kleinen Framework oder ner Lib ist das noch ok. Aber bei einer größeren Applikation wird das unübersichtlich und bei installation/deinstallation von zusätzlichen Sprachpaketen müssen die dateien über die ganze Ordnerhirachie verteilt werden.

Besser finde ich die Dateien in solch einer struktur zu sammeln

   lang
     |-de
        |- com.test.package1.properties
        |- com.test.package2.properties
     |-en
        |- com.test.package1.properties
        |- com.test.package2.properties
     |-dk
        |- com.test.package1.properties
        |- com.test.package2.properties

so muss man nich zwingend für jedes package ein bzw mehrere bundels erstellen sondern kann andere logische gruppierungen verwenden, wie z.B. pro Modul/Plugin eine Sprachdatei.

es trägt auch gut zur übersichtlichkeit bei, die logik direkt in den Actions zu implementieren, da so alles was zu einer Aktion gehöhrt schön in einer Klasse gekapselt ist... (Siehe OpenFTPConnectionAction den Dialog zur eingabe der Verbindungsdaten als inner Klasse hällt).




Als gegenbeispiel werde ich nun mal erklären wie ich das ganze in meinen Framework gelößt habe:

- die Strukturen der ActionComponents werden in einer XML datei definiert

- man kann gruppen in beliebiger tiefe bilden (untermenus)

- jeder action kann ein titel, icon und ein actioncommand zugeordnet werden

- Actions können über 2 verschiedene wegen realisiert werden

1. Im ActionManager wird eine von AbstractAction abgeleitete
Klasse unter dem zugehörigen actioncommand registriert
und aufgerufen

2. wenn man in der XML Datei dem command ein "CMD:" voranstellt
wird das actions Command (ohne "CMD:") der CommandLine übergenen.
In der CommandLine kann man nun entweder eine Klasse welche das
Interface Command implementiert registrieren oder per annotation
(@MethodCallCommandType(name="testCommand",
descr="Test Command",numArgs=3))
eine statische methode einbinden.

die xml dateien können dann im java programm wahlweise als MenuBar, PopupMenu, Toolbar oder l2fprod TaskPane über einen einfachen methodenaufruf zusammengebaut werden.

das ganze hat den vorteil, das man die Commands zu debug/oder scripting zwecken auch über eine graphische console bzw script datei ausführen kann und man erst die struktur in der xml datei definiert und diese ohne die Actions überhaupt zu implementieren testen kann.

auch ist es möglich schnell die actions zu ändern ohne den quellcode neu zu kompilieren.

<group>
 <item name="test">
  <action command="CMD:msg das ist ein test">
 </item>
</group>

zum testen, wird die actions ausgelößt(der menupunkt angeclickt) wird auf der Console "das ist ein test" ausgegeben, wenn das funtzt kann man einfach
das action command in der xml datei ändern und das programm neustarten...



beide methoden haben ihre vor und nachteil... letzendlich liegt es nur am geschmack des entwicklers welche man verwendet...


puh, jetzt hab ich ja zu meinem kram fast mehr geschrieben als zu deinem kram , was aber nichts negatives zu bedeuten hat...

[pago]

Hi, danke für's Feedback.

ActionContainer erbt von AbstractAction, richtig. Es wird durch den ComponentProvider
folgender Code zur Generierung eines Menüs erzeugt:

new JMenu(theActionContainer);

Das die actionPerformed-Methode nicht aufgerufen wird, liegt also an der Swing-Action-API.
Über Sinn und Unsinn darf man streiten, aber das maximale, was ein Menü beim "draufklicken"
machen könnte, wäre das Untermenü zu generieren ("on-demand", so zu sagen). Da weiß ich aber
nicht, ob Swing das mitmacht.
Du kannst einem ActionContainer übrigens auch einen anderen ActionContainer hinzufügen. Nur
falls das nicht klar geworden ist.

Dann bzgl. der ActionGroups. Es gibt ein Interface "StateAction" und Actions, die dieses
Interface implementieren verfügen über eine "getGroup"-Methode. Die ActionGroup-Klasse ist mit
der ButtonGroup-Klasse aus dem Standard-JDK vergleichbar, nur das sie mir ein paar mehr
Möglichkeiten bietet.
Alle Actions einer Gruppe müssen die selbe ("==") ActionGroup als
Parameter dieser Methode zurückgeben. Das wird meist durch eine gemeinsame Oberklasse
realisiert, die diese ActionGroup als statische Instanz besitzt und in der getGroup-Methode
zurückgibt.

Das gilt alles nur für "JRadioButton" und "JRadioButtonMenuItem".
Für "JCheckbox" und "JCheckboxMenuItem" liefert "getGroup" den Wert "null".

Du verwendest in jedem Fall aber noch "ganz normale" Actions, die StateAction implementieren.

Bzgl. I18N:
Ich hab mich als Standard an NetBeans orientiert, die das haargenau so machen.
Und ich würde NetBeans nicht als kleines Projekt bezeichnen. Spielt aber auch keine Rolle,
weil du das so machen kannst, wie du es haben möchtest.

AbstractSystemAction besitzt ne statische Methode "setProvider(ActionResourceProvider)", die
genau für diesen Fall existiert.
Schau dir einfach mal das Interface und die Standard-Implementation an. Meistens reicht es,
wenn du in getConfig "null" lieferst und in getString muss halt das ResourceBundle für das
Action-Objekt gefunden und dann der entsprechende Text zurückgegeben werden.

Allerdings frag ich mich da, ob du in deinem Beispiel nicht sowieso eine eigene
ResourceBundle-Implementation vorliegen hast, in die du das Action-System integrieren könntest.
Weil soweit ich weiß sucht ResourceBundle immer nach "Bundle_de_DE.properties", und nicht nach
"/lang/de/DE/Bundle.properties".
Beim "Standard" zu bleiben bringt aber z.B. den Vorteil, den Tool-Support verwenden zu können.
Zugegeben, das funktioniert bei meinem Framework aktuell dank des ".name" am key-ende auch noch
nicht, aber ich glaub das werd ich noch umändern...

Sooo... jetzt zu deinem.

die Strukturen der ActionComponents werden in einer XML datei definiert

Hatte ich bei der aller ersten SimpleEdit-Version so gemacht. Ist dann hinterher in einem
XUL-Klon eskaliert.
NetBeans macht das aber auch so - mag ich überhaupt nicht (ich denke einfach, dass
meine Java-Version sehr einfach ist und das ganze etwas geordnerter hält - außerdem ist die
Erweiterung etwas einfacher).

man kann gruppen in beliebiger tiefe bilden (untermenus)

Ist klar, muss ja auch sein.
(Deshalb am Anfang der Kommentar von mir bzgl. ActionContainer in ActionContainer einfügen)

Ansonsten sehe ich da doch recht starke Konzeptions-Unterschiede. In meinem Konzept
werden die Actions zuerst implementiert und die Struktur vernachlässigt, bzw. anderweitig
festgehalten. Was man im Endeffekt bevorzugt ist natürlich wieder Geschmackssache.
Wobei mich das auf die Idee bringt, dass ich mal versuchen könnte, etwas "ähnliches"
zu integrieren. Also "Generierung von ActionContainern auf Basis einer Datei".

Hmm... nach kurzem Nachdenken würde ich, denke ich, sowas hier recht gern haben:

menu id="main"
	menu id="file"
		item id="open.file" action="com.pagosoft.demo.OpenFileAction" icon="icons/openfile.png"
		item id="close.file" action="com.pagosoft.demo.CloseFileAction"
	menu id="syntax"
		item id="syntax.php" action="org.simpleedit.actions.syntax.PHPTokenMarkerAction" group="syntax"
		item id="syntax.html" action="org.simpleedit.actions.syntax.HTMLTokenMarkerAction" group="syntax"
	menu id="help"
		item id="show.help" action="com.pagosoft.demo.ShowHelpAction" accel="F1"
		item ref="com.pagosoft.demo.SomeActionObject@id.of.action"

Kommt natürlich drauf an, ob man die Datei von Hand editieren möchte, oder ob's per Programm
erledigt werden soll.
Wobei man meine Syntax oben vielleicht noch etwas anders machen könnte... ein bisschen
mehr wie Lisp wäre schön... aber das wäre nur (unnötiger) Syntax-Sugar, denke ich.

Ein Parser für das da oben ist schnell geschrieben, einen ActionContainer in sowas zu
verwandeln auch.

Hmm... API wäre in etwa so brauchbar:

ActionFactory fac = ActionFactory.getInstance();
fac.parse(SimpleEdit.getResourceAsStream("core.paf")); // core.paf => beinhaltet code von oben
ActionContainer main = fac.get("main");
JMenuBar mb = main.createMenuBar();

Irgendwo in nem Plugin:

ActionFactory.getInstance().parse("plugin.paf");

Und das würde dann Sachen aus dem Plugin ins Menü laden...


Lange Rede, kurzer Sinn: Mein Dateiformat da oben ist trotzdem noch ne Menge zu schreiben,
mit XML wäre es noch mehr, außer man registriert die Actions in der Factory, was aber nur
noch mehr Schreibarbeit ist. Speziell wo die IDE dir bei keinem der Formate wirklich
helfen kann. Klar, du könntest dir Plugins dafür schreiben, aber so ganz viel Sinn macht
das IMHO nicht.

Das einzige Argument, wo ich dir voll und ganz zustimme, ist dieses hier:

auch ist es möglich schnell die actions zu ändern ohne den quellcode neu zu kompilieren.

Das ist natürlich extremst nützlich, weswegen ich mir zumindest überlegen werde, ob ich's nicht
doch irgendwie einbauen möchte.

[beny_mcde]

Zitat von pago

Ich hab mich als Standard an NetBeans orientiert, die das haargenau so machen.

netbeans ist zwar internationalisierbar aber meines wissens gibts das nur in englisch.... warscheinlich weil sich keiner die mühe machen wollte über den gesamten klassenpfad(bei netbeans müsste er ziemlich groß sein) die bundels zu suchen und zu übersetzen.....

Zitat von page

Hatte ich bei der aller ersten SimpleEdit-Version so gemacht. Ist dann hinterher in einem
XUL-Klon eskaliert.

das kann passieren, aber wenn es sich nicht auf die performance niederschlägt ist das ja nicht unbedingt ein nachteil.

ich verwende die XML dateien nur bei menu's toolbars und taskpanes, der rest wird auch hardcodiert...
der vorteil von xml gegenüber einen eigenen dateiformat ist das es halt standartisiert ist und jeder dem XML kein fremdwort ist sich auch relativ schnell in jede xml sprache einarbeiten kann.
zur erklärung kann man noch eine DTD erzeugen, daraus lässt sich ganz gut erkennen welche elemente und attribute wo verwendet werden dürfen.

Zitat von page

Allerdings frag ich mich da, ob du in deinem Beispiel nicht sowieso eine eigene
ResourceBundle-Implementation vorliegen hast

ja hab ich. hab noch ein paar kleine features hinzugefügt.

alle aus einem bundel abgerufenen schlüssel werden wenn sie nicht existieren automatisch mit leerem inhalt hinzugefügt.
wenn man die sprache erst hinterher definieren will ist das ganz nützlich, ich lass das prog einmal durchlaufen und hab schon (fast) alle schlüssel in der datei stehen, das erspart schreib/kopier arbeit...

auch kann man variablen ein die strings einbinden.

 test.string1=Hier ein paar platzhalter: {1},{2} und {3}

 LanguagePack lang = LanguagePack.get('app.core');
 lang.getString('test.string1','bla1','bla2','bla3');

die variablen werden über varargs übergeben und in den beantragten string eingesetzt.

ausserdem werden alle <br>'s durch einen zeilenumbruch ersetzt,
somit kann man mehrzeiligen text in einem schlüssel aufbewahren, da wenn man die zeilenumbrüche mit \n reinschreibt werden die zeilen auch in der datei umgebrochen und nicht mehr als ein schlüssel/weret paar erkannt

LanguagePack beinhaltet einen PropertyManager, welcher die sprache in sich aufnimmt, wenn die sprache (zur laufzeit) gewechselt wird, werden alle angemeldeten language listeners benachrichtigt und können nun aus dem selben LanguagePack die Strings in der neuen sprache beziehen...



wie hast du die internationalisierung in der gui gelößt?
arbeitest du in den Klassen die sprache benötigen direkt mit den ResourceBundles oder hast du eine zwischenschicht, die teile der internationalisierung automatisiert?
kann man die sprache zur laufzeit umschalten?

[pago]

Du kannst auch sowas machen:

key = Text mit \
                  Zeilenumbruch

Der Vorteil beim Standardverfahren ist halt der Toolsupport. Mit IDEA 5.1 brauch ich mich darum überhaupt nicht mehr zu kümmern.

PgsAction verwendet direkt ResourceBundle. In SimpleEdit gibt es ein paar Hilfsfunktionen im Sinne von

SimpleEdit.getString(SomeClass.class, "key", "arg1", "arg2", "argN");

Aktuell kann man die Sprache überhaupt nicht ändern.
Und wenn ich mich irgendwann dazu entschließen sollte, dass einzubauen, dann wird das nur nach Neustart greifen.

Swing bietet keine besonders guten Möglichkeiten, sowas zu realisieren und ich denke nicht, dass ich das ändern möchte. Wenn ich es nämlich tun würde, dann wirklich gut und das beansprucht ne Menge arbeit.

So ungefähr:

LanguagePacks.setLocale(new Locale("de", "DE"));

Was zu einer vollständig automatischen aktualisierung aller GUI-Elemente führen würde. D.h. ohne Listener.
Was anderes kommt mir nicht in die Tüte.

Hmm... mit Annotations ließe sich das sogar vielleicht machen. Na ja. Muss ich mal ne Nacht drüber schlafen.

netbeans ist zwar internationalisierbar aber meines wissens gibts das nur in englisch.... warscheinlich weil sich keiner die mühe machen wollte über den gesamten klassenpfad(bei netbeans müsste er ziemlich groß sein) die bundels zu suchen und zu übersetzen.....

Ich denke eher, dass das daran liegt, dass es so unglaublich viel wäre.

der vorteil von xml gegenüber einen eigenen dateiformat ist das es halt standartisiert ist und jeder dem XML kein fremdwort ist sich auch relativ schnell in jede xml sprache einarbeiten kann.

Da wiederspreche ich, aber das spielt auch keine große Rolle.
Ich finde z.B. das Menü-Format von Blackbox/Fluxbox genauso einfach wie das von Openbox, nur dass das von den ersten beiden deutlich weniger Schreibarbeit bedeutet.

Na ja, das Problem ist einfach, dass ich für ein Action-Framework schlecht ein eigenes Resource-Loading implementieren. Das würde zu weit gehen.

[pago]

Man möge mir meine Faulheit verzeihen, aber noch ne Ankündigung pack ich heute nicht...

The PgsAction Framework is a simple, yet powerful framework for working with the Swing Action-API. It is optimized for use in dynamic contexts (for example: in cooperation with a Plugin-Framework).

Like most Pagosoft-products, this one is licensed under terms of the Apache Software License 2 - which means you may freely use it for whatever you'd like to.

We're currently working on the documentation, thus you'll need to read the Javadoc and look at the examples manually, while we're creating the documentation.

This libary might be used with Java 1.4, but has some additional features for 5.0.

Some features:
* Annotation based action creation (5.0 only)
* Creation of JMenuBar/JMenu/JPopupMenu/JToolBar and synchronization of these views with their models (a simple ListModel or a more specialized ActionContainer)
* Extension for working with Jidesofts Action-components
* Context sensitive actions
* Easy internationalization
* Automatic optimization of keystrokes for the Mac
* Flexible
* Easy to use

Take a look at it and be careful not to be scared by the short documentation. The JavaDoc contains most informations that could be needed and there are two simple samples.

Product website

With best regards
Patrick Gotthardt