Add @Config.Expose and related component info key.

Deprecate @Config.Preferred.

praxiscore-api/src/main/java/org/praxislive/core/ComponentInfo.java

@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  * 
- * Copyright 2023 Neil C Smith.
+ * Copyright 2024 Neil C Smith.
  * 
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU Lesser General Public License version 3 only, as
@@ -76,6 +76,18 @@ public class ComponentInfo extends PMap.MapBasedValue {
      */
     public static final String KEY_DISPLAY_HINT = "display-hint";
 
+    /**
+     * Optional key for adding a default list of control IDs to give extra
+     * priority to exposing to the user. Value must be an array.
+     * <p>
+     * It is up to any editor whether to use or ignore this property (eg. the
+     * PraxisLIVE graph editor will show exposed controls on the graph itself).
+     * If the editor supports overriding the default list of exposed controls,
+     * it should add the altered list under the same key in the
+     * {@link ComponentProtocol#META} property.
+     */
+    public static final String KEY_EXPOSE = "expose";
+
     private final OrderedMap<String, ControlInfo> controls;
     private final OrderedMap<String, PortInfo> ports;
     private final List<String> protocols;

praxiscore-code/src/main/java/org/praxislive/code/CodeConnector.java

@@ -33,7 +33,9 @@
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
 import java.util.TreeMap;
+import java.util.concurrent.CopyOnWriteArraySet;
 import java.util.function.Function;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
@@ -58,6 +60,7 @@
 import org.praxislive.core.ControlAddress;
 import org.praxislive.core.ComponentInfo;
 import org.praxislive.core.ComponentType;
+import org.praxislive.core.ControlInfo;
 import org.praxislive.core.Info;
 import org.praxislive.core.Lookup;
 import org.praxislive.core.Value;
@@ -66,6 +69,7 @@
 import org.praxislive.core.types.PString;
 import org.praxislive.core.services.LogBuilder;
 import org.praxislive.core.services.LogLevel;
+import org.praxislive.core.types.PArray;
 
 /**
  * Base class for analysing a {@link CodeDelegate} and creating the resources
@@ -95,6 +99,7 @@ public abstract class CodeConnector<D extends CodeDelegate> {
     private final Map<String, ControlDescriptor<?>> controls;
     private final Map<String, PortDescriptor<?>> ports;
     private final Map<String, ReferenceDescriptor<?>> refs;
+    private final Set<String> expose;
 
     private List<Plugin> plugins;
     private Map<String, ControlDescriptor<?>> extControls;
@@ -118,6 +123,7 @@ public CodeConnector(CodeFactory.Task<D> task, D delegate) {
         controls = new TreeMap<>();
         ports = new TreeMap<>();
         refs = new TreeMap<>();
+        expose = new CopyOnWriteArraySet<>();
     }
 
     /**
@@ -152,6 +158,12 @@ public LogBuilder getLog() {
         return log;
     }
 
+    // TODO - remove when @Config.Preferred removed.
+    @Deprecated(forRemoval = true)
+    final void exposeForPreferred(String id) {
+        expose.add(id);
+    }
+
     /**
      * Called by the CodeContext to access all processed control descriptors.
      * Subclasses may override to extend, but should ensure to call the
@@ -281,6 +293,12 @@ protected void buildBaseComponentInfo(Info.ComponentInfoBuilder cmp) {
         cmp.merge(ComponentProtocol.API_INFO);
         cmp.property(ComponentInfo.KEY_DYNAMIC, true);
         cmp.property(ComponentInfo.KEY_COMPONENT_TYPE, factory.componentType());
+        if (!expose.isEmpty()) {
+            cmp.property(ComponentInfo.KEY_EXPOSE,
+                    expose.stream()
+                            .map(PString::of)
+                            .collect(PArray.collector()));
+        }
     }
 
     /**
@@ -532,6 +550,11 @@ protected void analyseField(Field field) {
      */
     protected void analyseMethod(Method method) {
 
+        Config.Expose exp = method.getAnnotation(Config.Expose.class);
+        if (exp != null) {
+            expose.addAll(Arrays.asList(exp.value()));
+        }
+
         for (Plugin p : plugins) {
             if (p.analyseMethod(this, method)) {
                 return;

praxiscore-code/src/main/java/org/praxislive/code/PropertyControl.java

@@ -397,6 +397,9 @@ private static Descriptor create(CodeConnector<?> connector, int index,
                         binding.getDefaultValue(),
                         buildProperties(field));
             }
+            if (info.properties().getBoolean("preferred", false)) {
+                connector.exposeForPreferred(id);
+            }
             return new Descriptor(id, index, info, binding, propertyField, onChange, onError);
         }
 

praxiscore-code/src/main/java/org/praxislive/code/userapi/Config.java

@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright 2020 Neil C Smith.
+ * Copyright 2024 Neil C Smith.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU Lesser General Public License version 3 only, as
@@ -21,17 +21,22 @@
  */
 package org.praxislive.code.userapi;
 
+import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import org.praxislive.core.ComponentInfo;
+import org.praxislive.core.protocols.ComponentProtocol;
 
 /**
+ * Various annotations and support to control component configuration.
  *
- * 
  */
 public final class Config {
 
-    private Config() {}
-
+    private Config() {
+    }
+
     /**
      * Control automatic port creation for properties, triggers, etc.
      */
@@ -53,10 +58,32 @@ private Config() {}
      * This will add a key to the info for this feature. It is up to an editor
      * whether to use or ignore this key (eg. the PraxisLIVE graph editor will
      * show properties marked this way on the graph itself).
+     * <p>
+     * This option is deprecated in favour of {@link Expose}.
      */
     @Retention(RetentionPolicy.RUNTIME)
+    @Deprecated(forRemoval = true)
     public @interface Preferred {
 
     }
 
+    /**
+     * Default list of control IDs to give extra priority to exposing to the
+     * user.
+     * <p>
+     * The list of controls is added under the key
+     * {@link ComponentInfo#KEY_EXPOSE} in the component info.
+     */
+    @Retention(RetentionPolicy.RUNTIME)
+    @Target(ElementType.METHOD)
+    public @interface Expose {
+
+        /**
+         * List of control IDs to expose.
+         *
+         * @return list of IDs
+         */
+        String[] value();
+    }
+
 }