Home | History | Annotate | Download | only in api 
      1 /*
      2  * Copyright (C) 2010 The Android Open Source Project
      3  *
      4  * Licensed under the Eclipse Public License, Version 1.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.eclipse.org/org/documents/epl-v10.php
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package com.android.ide.common.api;
     18 
     19 import com.android.annotations.NonNull;
     20 import com.google.common.annotations.Beta;
     21 
     22 import java.util.List;
     23 
     24 /**
     25  * Metadata about a particular view. The metadata for a View can be found by asking the
     26  * {@link IClientRulesEngine} for the metadata for a given class via
     27  * {@link IClientRulesEngine#getMetadata}.
     28  * <p>
     29  * <b>NOTE: This is not a public or final API; if you rely on this be prepared
     30  * to adjust your code for the next tools release.</b>
     31  */
     32 @Beta
     33 public interface IViewMetadata {
     34     /**
     35      * Returns the display name views of this type (a name suitable to display to the
     36      * user, normally capitalized and usually but not necessarily tied to the
     37      * implementation class). To be clear, a specific view may have an id attribute and a
     38      * text attribute, <b>neither</b> of these is the display name. Instead, the class
     39      * android.widget.ZoomControls may have the display name "Zoom Controls", and an
     40      * individual view created into a layout can for example have the id "ZoomControl01".
     41      *
     42      * @return the user visible name of views of this type (never null)
     43      */
     44     @NonNull
     45     public String getDisplayName();
     46 
     47     /**
     48      * Gets the insets for this view
     49      *
     50      * @return the insets for this view
     51      */
     52     @NonNull
     53     public Margins getInsets();
     54 
     55     /**
     56      * Returns the {@link FillPreference} of this view
     57      *
     58      * @return the {@link FillPreference} of this view, never null but may be
     59      *     {@link FillPreference#NONE}
     60      */
     61     @NonNull
     62     public FillPreference getFillPreference();
     63 
     64     /**
     65      * Returns the most common attributes for this view.
     66      *
     67      * @return a list of attribute names (not including a namespace prefix) that
     68      *         are commonly set for this type of view, never null
     69      */
     70     @NonNull
     71     public List<String> getTopAttributes();
     72 
     73     /**
     74      * Types of fill behavior that views can prefer.
     75      * <p>
     76      * TODO: Consider better names. FillPolicy? Stretchiness?
     77      */
     78     public enum FillPreference {
     79         /** This view does not want to fill */
     80         NONE,
     81         /** This view wants to always fill both horizontal and vertical */
     82         BOTH,
     83         /** This view wants to fill horizontally but not vertically */
     84         WIDTH,
     85         /** This view wants to fill vertically but not horizontally */
     86         HEIGHT,
     87         /**
     88          * This view wants to fill in the opposite dimension of the context, e.g. in a
     89          * vertical context it wants to fill horizontally, and vice versa
     90          */
     91         OPPOSITE,
     92         /** This view wants to fill horizontally, but only in a vertical context */
     93         WIDTH_IN_VERTICAL,
     94         /** This view wants to fill vertically, but only in a horizontal context */
     95         HEIGHT_IN_HORIZONTAL;
     96 
     97         /**
     98          * Returns true if this view wants to fill horizontally, if the context is
     99          * vertical or horizontal as indicated by the parameter.
    100          *
    101          * @param verticalContext If true, the context is vertical, otherwise it is
    102          *            horizontal.
    103          * @return true if this view wants to fill horizontally
    104          */
    105         public boolean fillHorizontally(boolean verticalContext) {
    106             return (this == BOTH || this == WIDTH ||
    107                     (verticalContext && (this == OPPOSITE || this == WIDTH_IN_VERTICAL)));
    108         }
    109 
    110         /**
    111          * Returns true if this view wants to fill vertically, if the context is
    112          * vertical or horizontal as indicated by the parameter.
    113          *
    114          * @param verticalContext If true, the context is vertical, otherwise it is
    115          *            horizontal.
    116          * @return true if this view wants to fill vertically
    117          */
    118         public boolean fillVertically(boolean verticalContext) {
    119             return (this == BOTH || this == HEIGHT ||
    120                     (!verticalContext && (this == OPPOSITE || this == HEIGHT_IN_HORIZONTAL)));
    121         }
    122     }
    123 }
    124